Identify a solution for documenting our external API

[carrollgt91]

One of the main goals of the project is to expose end user data via a public API. A major part of this effort will be setting up a way of documenting this API effectively.

It would be great to have a couple of options as to how we could accomplish this to choose from.

The solution we want should have:

• great UX for consumers of the API
• a way to allow for multiple versions of documentation to be hosted simultaneously
• should allow for us to document both the API endpoints as well as general system-concepts
• should be easy to host
• should be open source

Nice to haves:

• "try this endpoint out" functionality that allows you to hit the API with credentials from your own account (assuming you're signed in)

[PlamenHristov]

Probably the go to answer here would be to use Swagger. What I've done in previous projects was to use flasger for the swagger part and flask_marshmallow for the automation around exposing the objects.

The annoying thing is that endpoints need to be documented like so:

def users_list(identity):
  """
  Get list of users.
  ...
  ---
  tags:
        - 'user'
    security:
        - JWT: []
    summary: List of users
    parameters:
      - name: exclude_admin
        in: query
        description: Optional parameter to for excluding certain users
        required: false
        schema:
          type: boolean
    responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserBriefResponse'
...

and for more complex endpoints it might get unwieldy. Though that could potentially be solved by keeping the endpoint documentation in a separate file, have a mapping between method names and swagger docstring and attach them dynamically at runtime.

Flasgger then extracts the yaml documentation from the doctring and serves the Swagger UI with all the niceties of being able to try out the the endpoints with/without authentication etc. From the list above it will support:

• great UX for consumers of the API :heavy_check_mark:
• a way to allow for multiple versions of documentation to be hosted simultaneously :heavy_check_mark:
• should allow for us to document both the API endpoints as well as general system-concepts :x:
• should be easy to host :heavy_check_mark:
• should be open source :heavy_check_mark:

Maybe we can leave the system-concept for the official documentation page? Let me know what you think overall?

[carrollgt91]

I think Swagger will work nicely for the main API, especially in the short run. We can definitely put a "landing page" on our docsite that can cover the general system concepts.