locations for openapi docs

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;

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 

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'