Merge pull request #33 from uc-cdis/fix/docs

fix(docs): fix issues with openapi generation, add required deps, pus…

manifestservice/manifests/__init__.py

@@ -164,16 +164,17 @@ def put_pfb_guid():
     Will create a new file named with the value of the GUID for the PFB in the user's s3 folder
     Post body: { "guid": "5183a350-9d56-4084-8a03-6471cafeb7fe" }
     ---
-    responses:
+
+    Returns:
         200:
             description: Success
-            Return value: ({ "filename" : "5183a350-9d56-4084-8a03-6471cafeb7fe" }, 200)
+            example: '({ "filename": "5183a350-9d56-4084-8a03-6471cafeb7fe" }, 200)'
         403:
             description: Unauthorized
-            Return value: ({ "error" : "<error-message>" }, 403)
+            example: '({ "error": "<error-message>" }, 403)'
         400:
             description: Bad GUID format
-            Return value: ({ "error" : "<error-message>" }, 400)
+            example: '({ "error": "<error-message>" }, 400)'
     """
 
     err, code = _authenticate_user()

openapi/swagger.yaml

@@ -2,92 +2,85 @@ definitions: {}
 info:
   contact:
     email: [email protected]
-  description: A service template for CDIS Gen 3 data commons. Code is available on
-    [GitHub](https://github.com/uc-cdis/template-repo).
+  description: A microservice that facilitates manifest creation and retrieval. Code
+    is available on [GitHub](https://github.com/uc-cdis/manifestservice).
   license:
     name: Apache 2.0
     url: http://www.apache.org/licenses/LICENSE-2.0.html
   termsOfService: http://cdis.uchicago.edu/terms/
-  title: Service template OpenAPI Specification
+  title: Manifest Service OpenAPI Specification
   version: '1.0'
 paths:
-  /_status:
-    get:
-      responses:
-        '200':
-          description: Healthy
-        default:
-          description: Unhealthy
-      summary: Health check endpoint
-      tags:
-      - system
-  /admin:
+  /:
     get:
+      description: We find the appropriate folder ("prefix") in the bucket by asking
+        Fence for<br/>info about the user's access token.<br/>
       responses:
         '200':
           description: Success
-        '401':
-          description: Unauthorized
-      summary: Admin endpoint
-      tags:
-      - admin
-  /admin/is_admin:
-    get:
-      responses:
-        '200':
-          description: User is admin
         '403':
-          description: User is not admin
-      summary: Admin endpoint
-      tags:
-      - admin
-  /something:
-    get:
+          description: Unauthorized
+      summary: Returns a list of filenames corresponding to the user's manifests.
+    post:
       responses:
         '200':
           description: Success
-      summary: Get something
+        '400':
+          description: Bad manifest format
+        '403':
+          description: Unauthorized
+      summary: Add manifest to s3 bucket. See the README for the format of this file.
     put:
       responses:
         '200':
           description: Success
-      summary: Put something
-  /something/bar:
-    get:
-      responses:
-        '200':
-          description: Success
-      summary: bar!
-  /something/foo/{param}:
+        '400':
+          description: Bad manifest format
+        '403':
+          description: Unauthorized
+      summary: Add manifest to s3 bucket. See the README for the format of this file.
+  /_status:
     get:
-      parameters:
-      - in: path
-        name: param
-        required: true
-        type: string
       responses:
         '200':
-          description: Success
-      summary: foo!
-  /something/put-get:
+          description: Healthy
+        default:
+          description: Unhealthy
+      summary: Health check endpoint
+      tags:
+      - system
+  /cohorts:
     get:
-      description: <br/>GET and PUT have the same documentation:<br/>
+      description: PFBs. We find the appropriate folder ("prefix") in the bucket by
+        asking Fence for<br/>info about the user's access token.<br/>
       responses:
         '200':
           description: Success
-      summary: Several methods for the same function
+        '403':
+          description: Unauthorized
+      summary: Returns a list of filenames -- which are GUIDs -- corresponding to
+        the user's exported
+    post:
+      description: 'Will create a new file named with the value of the GUID for the
+        PFB in the user''s s3 folder<br/>Post body: { "guid": "5183a350-9d56-4084-8a03-6471cafeb7fe"
+        }<br/>'
+      summary: Add PFB GUID to s3 bucket.
     put:
-      description: <br/>GET and PUT have the same documentation:<br/>
-      responses:
-        '200':
-          description: Success
-      summary: Several methods for the same function
-  /user_endpoint:
+      description: 'Will create a new file named with the value of the GUID for the
+        PFB in the user''s s3 folder<br/>Post body: { "guid": "5183a350-9d56-4084-8a03-6471cafeb7fe"
+        }<br/>'
+      summary: Add PFB GUID to s3 bucket.
+  /file/{file_name}:
     get:
+      description: The argument is the filename of the manifest you want to downloaded,<br/>of
+        the form "manifest-timestamp".json. The user folder prefix is encapsulated
+        from<br/>the caller -- just provide the basepath.<br/>
       responses:
         '200':
           description: Success
-        '401':
+        '400':
+          description: Bad request format
+        '403':
           description: Unauthorized
-      summary: User endpoint
+      summary: Returns the requested manifest file from the user's folder.
 swagger: '2.0'