Merge pull request #428 from codeforboston/dmalone/oas-filtering

Add additional filtering options to the OAS

Author: DMalone87

oas/2.0/agencies.yaml

@@ -27,6 +27,14 @@ paths:
       summary: "Get Agencies"
       operationId: "getAgencies"
       description: "Get a list of all agencies"
+      parameters: 
+        - $ref: '../common/pagination.yaml#/components/parameters/page'
+        - $ref: '../common/pagination.yaml#/components/parameters/per_page'
+        - $ref: '#/components/parameters/jurisdiction'
+        - $ref: '#/components/parameters/name'
+        - $ref: '#/components/parameters/zip_code'
+        - $ref: '#/components/parameters/city'
+        - $ref: '#/components/parameters/state'
       tags: 
         -  Agencies
       responses:
@@ -101,17 +109,29 @@ paths:
                 $ref: '#/components/schemas/Agency'
         '400':
           $ref: '../common/error.yaml#/components/responses/validationError'
+        '404':
+          $ref: '../common/error.yaml#/components/responses/notFoundError'
   /agencies/{agency_uid}/officers:
-    parameters:
-      - name: "agency_uid"
-        in: "path"
-        description: "The uid of the agency you want to retrieve."
-        required: true
-        schema:
-          type: "string"
     get:
       summary: "Get Officers"
       operationId: "getOfficers"
+      parameters:
+        - name: "agency_uid"
+          in: "path"
+          description: "The uid of the agency you want to retrieve."
+          required: true
+          schema:
+            type: "string"
+        - $ref: '../common/pagination.yaml#/components/parameters/page'
+        - $ref: '../common/pagination.yaml#/components/parameters/per_page'
+        - $ref: 'officers.yaml#/components/parameters/active_after'
+        - $ref: 'officers.yaml#/components/parameters/active_before'
+        - $ref: 'officers.yaml#/components/parameters/agency'
+        - $ref: 'officers.yaml#/components/parameters/rank'
+        - $ref: 'officers.yaml#/components/parameters/unit'
+        - $ref: 'officers.yaml#/components/parameters/name'
+        - $ref: 'officers.yaml#/components/parameters/ethnicity'
+        - $ref: 'officers.yaml#/components/parameters/badge_number'
       description: >
         Get a list of all of the officers who have been employed
         by a given agency.
@@ -124,13 +144,24 @@ paths:
             application/json:
               schema:
                 $ref: officers.yaml#/components/schemas/OfficerList
+        '400':
+          $ref: '../common/error.yaml#/components/responses/validationError'
+        '404':
+          $ref: '../common/error.yaml#/components/responses/notFoundError'
     put: 
       summary: "Add Employment Records"
       operationId: "addOfficers"
       description: >
         Adds officer employment records to an agency. Can only
         add records for officers that already exist in the database.
         User must be a contributor.
+      parameters:
+        - name: "agency_uid"
+          in: "path"
+          description: "The uid of the agency you want to retrieve."
+          required: true
+          schema:
+            type: "string"
       tags: 
         -  Units
       requestBody:
@@ -153,17 +184,23 @@ paths:
         '404':
           $ref: '../common/error.yaml#/components/responses/notFoundError'
   /agencies/{agency_uid}/units:
-    parameters:
-      - name: "agency_uid"
-        in: "path"
-        description: "The uid of the agency you want to retrieve."
-        required: true
-        schema:
-          type: "string"
     get:
       summary: "Get Units"
       operationId: "getUnits"
       description: "Get a list of all units for a given agency."
+      parameters:
+        - name: "agency_uid"
+          in: "path"
+          description: "The uid of the agency you want to retrieve units for."
+          required: true
+          schema:
+            type: "string"
+        - $ref: '../common/pagination.yaml#/components/parameters/page'
+        - $ref: '../common/pagination.yaml#/components/parameters/per_page'
+        - $ref: '#/components/parameters/name'
+        - $ref: '#/components/parameters/zip_code'
+        - $ref: '#/components/parameters/city'
+        - $ref: '#/components/parameters/state'
       tags: 
         -  Units
       responses:
@@ -179,6 +216,13 @@ paths:
       summary: "Create Unit"
       operationId: "createUnit"
       description: "Adds a unit or command to an existing agency. User must be a contributor."
+      parameters:
+        - name: "agency_uid"
+          in: "path"
+          description: "The uid of the agency you want to retrieve units for."
+          required: true
+          schema:
+            type: "string"
       tags: 
         -  Units
       requestBody:
@@ -197,20 +241,9 @@ paths:
                 $ref: "#/components/schemas/CreateUnit"
         '400':
           $ref: '../common/error.yaml#/components/responses/validationError'
+        '404':
+          $ref: '../common/error.yaml#/components/responses/notFoundError'
   /agencies/{agency_uid}/units/{unit_uid}:
-    parameters:
-      - name: "agency_uid"
-        in: "path"
-        description: "The uid of the agency you want to retrieve."
-        required: true
-        schema:
-          type: "string"
-      - name: "unit_uid"
-        in: "path"
-        description: "The uid of the agency you want to retrieve."
-        required: true
-        schema:
-          type: "string"
     get:
       summary: "Get Unit"
       operationId: "getUnit"
@@ -225,17 +258,40 @@ paths:
           required: true
           schema:
             type: "string"
+        - name: "unit_uid"
+          in: "path"
+          description: "The uid of the unit you want to retrieve."
+          required: true
+          schema:
+            type: "string"
       responses:
         "200":
           description: "A JSON array of unit objects"
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Unit"
+        '400':
+          $ref: '../common/error.yaml#/components/responses/validationError'
+        '404':
+          $ref: '../common/error.yaml#/components/responses/notFoundError'
     patch:
       summary: "Update Unit"
       operationId: "updateUnit"
       description: "Update an existing unit. User must be a contributor."
+      parameters:
+        - name: "agency_uid"
+          in: "path"
+          description: "The uid of the agency you want to retrieve units for."
+          required: true
+          schema:
+            type: "string"
+        - name: "unit_uid"
+          in: "path"
+          description: "The uid of the unit you want to retrieve."
+          required: true
+          schema:
+            type: "string"
       tags: 
         -  Units
       requestBody:
@@ -254,12 +310,50 @@ paths:
                 $ref: "#/components/schemas/Unit"
         '400':
           $ref: '../common/error.yaml#/components/responses/validationError'
+        '404':
+          $ref: '../common/error.yaml#/components/responses/notFoundError'
 components:
   securitySchemes:
     bearerAuth:
       type: http
       scheme: bearer
       bearerFormat: JWT
+  parameters:
+    jurisdiction:
+      name: "jurisdiction"
+      in: "query"
+      description: "Filter agencies by jurisdiction"
+      required: false
+      schema:
+        type: "string"
+    zip_code:
+      name: "zip_code"
+      in: "query"
+      description: "Filter by zip code"
+      required: false
+      schema:
+        type: "string"
+    city:
+      name: "city"
+      in: "query"
+      description: "Filter by city"
+      required: false
+      schema:
+        type: "string"
+    state:
+      name: "state"
+      in: "query"
+      description: "Filter by state"
+      required: false
+      schema:
+        type: "string"
+    name:
+      name: "name"
+      in: "query"
+      description: "Filter by name"
+      required: false
+      schema:
+        type: "string"
   schemas:
     BaseAgency:
       type: "object"

oas/2.0/authentication.yaml

@@ -14,15 +14,13 @@ x-readme:
   explorer-enabled: true
   proxy-enabled: true
   samples-enabled: true
-security:
-  - bearerAuth: []
 tags:
   - name: "Authentication"
     description: "API for authenticating and creating user accounts."
 paths:
   /auth/register:
     post:
-      summary: "register User Account"
+      summary: "Register New Account"
       operationId: "register"
       description: "Create a new user account."
       tags: 
@@ -45,7 +43,7 @@ paths:
           $ref: '../common/error.yaml#/components/responses/conflictError'
   /auth/login:
     post:
-      summary: "Log in"
+      summary: "Log In"
       operationId: "login"
       description: "Log in to an existing user account."
       tags: 
@@ -65,7 +63,9 @@ paths:
         '400':
           $ref: '../common/error.yaml#/components/responses/validationError'
   /auth/refresh:
-    post: 
+    post:
+      security:
+        - bearerAuth: []
       summary: "Refresh Access Token"
       operationId: "refreshToken"
       description: >
@@ -85,7 +85,9 @@ paths:
           $ref: '../common/error.yaml#/components/responses/unauthorizedError'
   /auth/logout:
     post:
-      summary: "Log out"
+      security:
+        - bearerAuth: []
+      summary: "Log Out"
       operationId: "logout"
       description: "Revokes the access token used to autheticate this request."
       tags: 
@@ -101,7 +103,9 @@ paths:
           $ref: '../common/error.yaml#/components/responses/unauthorizedError'
   /auth/whoami:
     get:
-      summary: "Who Am I"
+      security:
+        - bearerAuth: []
+      summary: "Current User"
       operationId: "whoami"
       description: "Returns the user that matches the access token used to authenticate the request."
       tags: