Enhancement request: better management of API documentation

[hurtigcodes]

Hi, I would like to create an enhancement request on behalf of the Norwegian NRC.

The current ways to manage API documentation in Swagger can be improved. It currently demands a developer to go in and make modifications and rebuild the code base. Whenever a new release is available we need to check and update docs. Also, the code readability is made worse with long annotations such as comments, examples and translations which adds to the 'SI official docs'.

We suggest users may externally modify said documentation in such as a JSON or YAML file (OAS3 has something like this I believe) or even the current application.properties and feed it to the app during startup.

[kaicode]

The dev team are working on upgrading to OpenAPI Spec 3 as a side effect of another fix. I wonder if an external yaml api-doc should be generated as part of the build process for you to modify?

[kaicode]

Could you confirm if these API doc enhancements are translations or additional documentation that could be added upstream?

[hurtigcodes]

The latter, namely additional documentation that could be added upstream.

[hurtigcodes]

We don't do localization or anything like that (if that is what you imply). We sometimes translate or 'technically vulgarize' some hard to read docs, however.

[kaicode]

If you could make these changes available to us we may be able to simply add them into the official snowstorm version? That may benefit other implementors. We could still investigate the OpenAPI Spec 3 too if still needed.

[rorydavidson]

I lean strongly to the OpenAPI spec as that would allow us to publish outside of online swagger documentation (see the old SCT Snapshot API documentation, now deprecated).

[hurtigcodes]

OK! I'll check in with the team to decide what docs we can commit to the intl repo.

Agreed, the OpenAPI approach is quite neat!

[hurtigcodes]

Another need which may be satisfied with OAS: easy to mark parameters as optional/mandatory.

Also, it looks like you can define reusable parameter schemas with regex pattern matching which may help input validation:

components:
  schemas:
    my_model_identifier:
      type: string
      format: ^[a-z]{3}[0-9]{10}$
    my_model:
      type: object
      parameters:
        id:
          $ref: '#/components/schemas/my_model_identifier'
        other_field:
          type: string

[kaicode]

I agree that this would be a great improvement to the API documentation, most of the parameters within the request body are optional.