API documentation

Some approaches you can take when working on a project that exposes either an external or internal API.

Swagger, a.k.a. OpenAPI Specification

There are two steps to using this format:

• generating the swagger file
• generating the documentation from the swagger file

and there are multiple solutions for each step.

Generating the swagger file

By hand

Or more likely using the swagger editor.

Using a modelling tool

E.g. stoplight

From code

TODO: Just adding those links here in the hope someone can elaborate:

https://github.com/Vizzuality/mgis/blob/develop/mgis-api/src/modules/impact-factors/impactfactors.entity.ts#L17

https://github.com/Vizzuality/mgis/blob/develop/mgis-api/src/modules/submissions/submissions.controller.ts#L65

From tests

TODO

https://github.com/zipmark/rspec_api_documentation

https://github.com/rswag/rswag

Documentation from the swagger file

ReDoc

Example: Trase Public API

Non-swagger

RW API - Slate

For documentation in RW API, we use a fork of the well-known tool Slate. Contributions to the docs are made via PRs to the forked repo, and the hosting is done using Github pages.

This option for documentation is completely decoupled from the source code of each MS of the RW API.

Other concerns: generating client SDKs

TODO https://swagger.io/tools/swagger-codegen/