Auto-generate human-readable API documentation from OpenAPI, JSON Schema documents

[erickpeirson]

We would like to generate and serve human-readable API documentation for NG APIs based on OpenAPI (v3) and JSON Schema documents.

Requirements:

1. Must be able to automatically (or mostly automatically) aggregate those documents so that they can be served together on one site.
2. Must be able to deploy the human-readable documentation as a Docker container. The container will run behind NGINX, so the entry point can be an application server like uWSGI.
3. The presentation of the documentation must generally align with arXiv color schemes, font choices, and other design practices. There is some flexibility as to what that means.

Open question: where should published OpenAPI/JSON Schema docs for each API live? We could just leave them in their respective GitHub repos, push them to an S3 bucket, something else? Should not involve manual file-shuffling.

Tooling:

• Consider https://github.com/wework/speccy for aggregating OpenAPI docs.
• Swagger-UI (https://github.com/swagger-api/swagger-ui) looks pretty good for display.

Background

We have quite a few NG APIs under development that use a combination of OpenAPI and JSON Schema to document their structure and behavior. For example:

• https://github.com/arXiv/arxiv-search/tree/master/schema
• https://github.com/arXiv/arxiv-filemanager/tree/master/schema

These are usually stored at schema/ off the root of the repository. The OpenAPI docs refer to JSON Schema documents, usually in schema/resources/, using a relative $ref. For example:

      responses:
        '200':
          description: All arXiv papers that respond to specified query.
          content:
            application/json:
              schema:
                $ref: './resources/DocumentSet.json#'

We want to pull these together into a single presentation that can be deployed as part of the arXiv API gateway.

Cross-reference: ARXIVNG-1329

[JaimieMurdock]

Quickly looking at the Swagger-UI docs, it seems we are in good shape. The headers we use don't overlap with the Limitations.

The major issue for Community Contributors may be with CORS. If running swagger-ui local with a local copy of the repo, then this should be side-stepped, but it will be an issue for the eventual deployment. We will need to make sure the swagger.json/swagger.yaml files are externally exposed. Perhaps the easiest strategy is enabling CORS on the schema directory?