From 2bebfb0b8580a6bee22ac7abd30033e01b59fa3f Mon Sep 17 00:00:00 2001 From: David Bomba Date: Wed, 26 Feb 2025 21:12:47 +1100 Subject: [PATCH] locations for openapi docs --- app/Http/Controllers/QuoteController.php | 2 +- app/Services/Invoice/LocationData.php | 34 +-- openapi/components/schemas/location.yaml | 84 ++++++ openapi/paths/locations.yaml | 340 +++++++++++++++++++++++ 4 files changed, 442 insertions(+), 18 deletions(-) create mode 100644 openapi/components/schemas/location.yaml create mode 100644 openapi/paths/locations.yaml diff --git a/app/Http/Controllers/QuoteController.php b/app/Http/Controllers/QuoteController.php index 7b246a228f..2b78bd07c5 100644 --- a/app/Http/Controllers/QuoteController.php +++ b/app/Http/Controllers/QuoteController.php @@ -525,7 +525,7 @@ class QuoteController extends BaseController return response(['message' => 'Please verify your account to send emails.'], 400); } - if (Ninja::isHosted() && $user->account->emailQuotaExceeded()) { + if (Ninja::isHosted() && $user->account->emailQuotaExceeded()) { return response(['message' => ctrans('texts.email_quota_exceeded_subject')], 400); } diff --git a/app/Services/Invoice/LocationData.php b/app/Services/Invoice/LocationData.php index 97337e288a..fbe33d6eca 100644 --- a/app/Services/Invoice/LocationData.php +++ b/app/Services/Invoice/LocationData.php @@ -113,7 +113,7 @@ class LocationData extends AbstractService } } - private function getBusinessAddress(): ?string + private function getBusinessAddress(): string { $str = ' '; @@ -147,11 +147,11 @@ class LocationData extends AbstractService if ($city || $state || $postalCode) { return $this->entity->present()->cityStateZip($city, $state, $postalCode, $swap); } else { - return false; + return null; } } - private function getShippingAddress(): ?string + private function getShippingAddress(): string { $str = ' '; @@ -174,7 +174,7 @@ class LocationData extends AbstractService } - private function getBusinessAddress1(): ?string + private function getBusinessAddress1(): string { if ($this->businessLocation) { return $this->businessLocation->address1 ?? ''; @@ -183,7 +183,7 @@ class LocationData extends AbstractService return $this->entity->client->address1 ?? ''; } - private function getBusinessAddress2(): ?string + private function getBusinessAddress2(): string { if ($this->businessLocation) { return $this->businessLocation->address2 ?? ''; @@ -192,7 +192,7 @@ class LocationData extends AbstractService return $this->entity->client->address2 ?? ''; } - private function getBusinessCity(): ?string + private function getBusinessCity(): string { if ($this->businessLocation) { return $this->businessLocation->city ?? ''; @@ -201,7 +201,7 @@ class LocationData extends AbstractService return $this->entity->client->city ?? ''; } - private function getBusinessState(): ?string + private function getBusinessState(): string { if ($this->businessLocation) { return $this->businessLocation->state ?? ''; @@ -210,7 +210,7 @@ class LocationData extends AbstractService return $this->entity->client->state ?? ''; } - private function getBusinessPostalCode(): ?string + private function getBusinessPostalCode(): string { if ($this->businessLocation) { return $this->businessLocation->postal_code ?? ''; @@ -219,7 +219,7 @@ class LocationData extends AbstractService return $this->entity->client->postal_code ?? ''; } - private function getBusinessCountryName(): ?string + private function getBusinessCountryName(): string { if ($this->businessLocation) { return $this->businessLocation->country->name; @@ -228,7 +228,7 @@ class LocationData extends AbstractService return $this->entity->client->country->name; } - private function getBusinessCountryCode(): ?string + private function getBusinessCountryCode(): string { if ($this->businessLocation) { return $this->businessLocation->country->iso_3166_2; @@ -237,7 +237,7 @@ class LocationData extends AbstractService return $this->entity->client->country->iso_3166_2; } - private function getShippingAddress1(): ?string + private function getShippingAddress1(): string { if ($this->shippingLocation) { return $this->shippingLocation->address1 ?? ''; @@ -246,7 +246,7 @@ class LocationData extends AbstractService return $this->entity->client->shipping_address1 ?? ''; } - private function getShippingAddress2(): ?string + private function getShippingAddress2(): string { if ($this->shippingLocation) { return $this->shippingLocation->address2 ?? ''; @@ -255,7 +255,7 @@ class LocationData extends AbstractService return $this->entity->client->shipping_address2 ?? ''; } - private function getShippingCity(): ?string + private function getShippingCity(): string { if ($this->shippingLocation) { return $this->shippingLocation->city ?? ''; @@ -264,7 +264,7 @@ class LocationData extends AbstractService return $this->entity->client->shipping_city ?? ''; } - private function getShippingState(): ?string + private function getShippingState(): string { if ($this->shippingLocation) { return $this->shippingLocation->state ?? ''; @@ -273,7 +273,7 @@ class LocationData extends AbstractService return $this->entity->client->shipping_state ?? ''; } - private function getShippingPostalCode(): ?string + private function getShippingPostalCode(): string { if ($this->shippingLocation) { return $this->shippingLocation->postal_code ?? ''; @@ -282,7 +282,7 @@ class LocationData extends AbstractService return $this->entity->client->shipping_postal_code ?? ''; } - private function getShippingCountryName(): ?string + private function getShippingCountryName(): string { if ($this->shippingLocation && $this->shippingLocation->country) { return $this->shippingLocation->country->name; @@ -291,7 +291,7 @@ class LocationData extends AbstractService return $this->entity->client->shipping_country->name ?? $this->entity->company->country()->name; } - private function getShippingCountryCode(): ?string + private function getShippingCountryCode(): string { if ($this->shippingLocation && $this->shippingLocation->country) { return $this->shippingLocation->country->iso_3166_2; diff --git a/openapi/components/schemas/location.yaml b/openapi/components/schemas/location.yaml new file mode 100644 index 0000000000..3590fa3540 --- /dev/null +++ b/openapi/components/schemas/location.yaml @@ -0,0 +1,84 @@ + Location: + properties: + id: + description: 'The location hashed id' + type: string + example: Kd5S2M + name: + description: 'The location name' + type: string + example: 'Warehouse A' + address1: + description: 'The first line of the address' + type: string + example: '123 Business Street' + address2: + description: 'The second line of the address' + type: string + example: 'Suite 100' + city: + description: 'The city name' + type: string + example: 'San Francisco' + state: + description: 'The state or region' + type: string + example: 'CA' + postal_code: + description: 'The postal or zip code' + type: string + example: '94107' + country_id: + description: 'The ID of the associated country' + type: string + example: '840' + custom_value1: + description: 'Custom field value 1' + type: string + nullable: true + custom_value2: + description: 'Custom field value 2' + type: string + nullable: true + custom_value3: + description: 'Custom field value 3' + type: string + nullable: true + custom_value4: + description: 'Custom field value 4' + type: string + nullable: true + is_deleted: + description: 'Indicates if the location has been deleted' + type: boolean + example: false + is_shipping_location: + description: 'Indicates if this is a shipping location' + type: boolean + example: true + user_id: + description: 'The user hashed id' + type: string + example: Opnel5aKBz + readOnly: true + assigned_user_id: + description: 'The assigned user hashed id' + type: string + example: Opnel5aKBz + client_id: + description: 'The client hashed id' + type: string + example: Opnel5aKBz + vendor_id: + description: 'The vendor hashed id' + type: string + example: Opnel5aKBz + created_at: + description: 'Timestamp of when the location was created' + type: integer + example: 1623456789 + updated_at: + description: 'Timestamp of when the location was last updated' + type: integer + example: 1623456999 + type: object \ No newline at end of file diff --git a/openapi/paths/locations.yaml b/openapi/paths/locations.yaml new file mode 100644 index 0000000000..2238943100 --- /dev/null +++ b/openapi/paths/locations.yaml @@ -0,0 +1,340 @@ + /api/v1/locations: + get: + tags: + - locations + summary: 'List locations' + description: | + When retrieving a list of locations you can chain query parameters to filter the dataset. For example: + + ``` + /api/v1/locations?name=warehouse* + ``` + + You can also sort the results: + + ``` + /api/v1/locations?sort=name|desc + ``` + + For pagination, use per_page and page parameters: + + ``` + /api/v1/locations?per_page=15&page=2 + ``` + + The default per_page value is 20. + operationId: getLocations + parameters: + - $ref: '#/components/parameters/X-API-TOKEN' + - $ref: '#/components/parameters/X-Requested-With' + - $ref: '#/components/parameters/index' + - name: name + in: query + description: | + Filter by location name + + ```html + ?name=warehouse + ``` + required: false + schema: + type: string + example: warehouse + - name: sort + in: query + description: | + Returns the list sorted by column in ascending or descending order. + + ```html + ?sort=name|desc + ``` + required: false + schema: + type: string + example: name|desc + responses: + 200: + description: 'A list of locations' + headers: + X-MINIMUM-CLIENT-VERSION: + $ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + content: + application/json: + schema: + $ref: '#/components/schemas/Location' + 401: + $ref: '#/components/responses/401' + 403: + $ref: '#/components/responses/403' + 422: + $ref: '#/components/responses/422' + 429: + $ref: '#/components/responses/429' + default: + $ref: '#/components/responses/default' + + post: + tags: + - locations + summary: 'Create location' + description: 'Adds a location to a company' + operationId: storeLocation + parameters: + - $ref: '#/components/parameters/X-API-TOKEN' + - $ref: '#/components/parameters/X-Requested-With' + - $ref: '#/components/parameters/index' + requestBody: + description: Location object that needs to be added to the company + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/LocationRequest' + responses: + 200: + description: 'Returns the saved location object' + headers: + X-MINIMUM-CLIENT-VERSION: + $ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + content: + application/json: + schema: + $ref: '#/components/schemas/Location' + 401: + $ref: '#/components/responses/401' + 403: + $ref: '#/components/responses/403' + 422: + $ref: '#/components/responses/422' + 429: + $ref: '#/components/responses/429' + default: + $ref: '#/components/responses/default' + + '/api/v1/locations/{id}': + get: + tags: + - locations + summary: 'Show location' + description: 'Displays a location by id' + operationId: showLocation + parameters: + - $ref: '#/components/parameters/X-API-TOKEN' + - $ref: '#/components/parameters/X-Requested-With' + - $ref: '#/components/parameters/index' + - name: id + in: path + description: 'The Location Hashed ID' + required: true + schema: + type: string + format: string + example: D2J234DFA + responses: + 200: + description: 'Returns the location object' + headers: + X-MINIMUM-CLIENT-VERSION: + $ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + content: + application/json: + schema: + $ref: '#/components/schemas/Location' + 401: + $ref: '#/components/responses/401' + 403: + $ref: '#/components/responses/403' + 422: + $ref: '#/components/responses/422' + 429: + $ref: '#/components/responses/429' + default: + $ref: '#/components/responses/default' + + put: + tags: + - locations + summary: 'Update location' + description: 'Handles the updating of a location by id' + operationId: updateLocation + parameters: + - $ref: '#/components/parameters/X-API-TOKEN' + - $ref: '#/components/parameters/X-Requested-With' + - $ref: '#/components/parameters/index' + - name: id + in: path + description: 'The Location Hashed ID' + required: true + schema: + type: string + format: string + example: D2J234DFA + requestBody: + description: Location object that needs to be updated + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/LocationRequest' + responses: + 200: + description: 'Returns the location object' + headers: + X-MINIMUM-CLIENT-VERSION: + $ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + content: + application/json: + schema: + $ref: '#/components/schemas/Location' + 401: + $ref: '#/components/responses/401' + 403: + $ref: '#/components/responses/403' + 422: + $ref: '#/components/responses/422' + 429: + $ref: '#/components/responses/429' + default: + $ref: '#/components/responses/default' + + delete: + tags: + - locations + summary: 'Delete location' + description: 'Handles the deletion of a location by id' + operationId: deleteLocation + parameters: + - $ref: '#/components/parameters/X-API-TOKEN' + - $ref: '#/components/parameters/X-Requested-With' + - name: id + in: path + description: 'The Location Hashed ID' + required: true + schema: + type: string + format: string + example: D2J234DFA + responses: + 200: + description: 'Returns a HTTP status' + headers: + X-MINIMUM-CLIENT-VERSION: + $ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + 401: + $ref: '#/components/responses/401' + 403: + $ref: '#/components/responses/403' + 422: + $ref: '#/components/responses/422' + 429: + $ref: '#/components/responses/429' + default: + $ref: '#/components/responses/default' + + /api/v1/locations/create: + get: + tags: + - locations + summary: 'Blank Location' + description: 'Returns a blank object with default values' + operationId: getLocationsCreate + parameters: + - $ref: '#/components/parameters/X-API-TOKEN' + - $ref: '#/components/parameters/X-Requested-With' + - $ref: '#/components/parameters/index' + responses: + 200: + description: 'A blank location object' + headers: + X-MINIMUM-CLIENT-VERSION: + $ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + content: + application/json: + schema: + $ref: '#/components/schemas/Location' + 401: + $ref: '#/components/responses/401' + 403: + $ref: '#/components/responses/403' + 422: + $ref: '#/components/responses/422' + 429: + $ref: '#/components/responses/429' + default: + $ref: '#/components/responses/default' + + /api/v1/locations/bulk: + post: + tags: + - locations + summary: 'Bulk location actions' + description: | + Bulk actions allow to make changes to multiple locations in a single request. The following actions are supported: + + - archive + - restore + - delete + + All of these actions require an array of location ids to perform the requested action on ie. + + "ids":['id1','id2'] + operationId: bulkLocations + parameters: + - $ref: '#/components/parameters/X-API-TOKEN' + - $ref: '#/components/parameters/X-Requested-With' + - $ref: '#/components/parameters/index' + requestBody: + description: 'Bulk action array' + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GenericBulkAction' + responses: + 200: + description: 'The Location list Response of the updated locations that were bulk updated' + headers: + X-MINIMUM-CLIENT-VERSION: + $ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + content: + application/json: + schema: + $ref: '#/components/schemas/Location' + 401: + $ref: '#/components/responses/401' + 403: + $ref: '#/components/responses/403' + 422: + $ref: '#/components/responses/422' + 429: + $ref: '#/components/responses/429' + default: + $ref: '#/components/responses/default' \ No newline at end of file