Swagger UI

[MicahWW]

Documenting the endpoint using Swagger will greatly help define what the API is expecting to receive and return because as of writing this many functions have temporary holder returns that don't give any useful information. This will be ongoing but this issue is to track the initial setup of the Swagger documentation.

There are a few different ways to edit and view:

• Editor and Viewer as a VS Code extension
  • This is probably the easiest but I haven't heard of 42Crunch (the publisher) before
  • PRO - Helpful for editing as it has IntelliSense
  • CON - Rendering the UI seems to be slow
• Editor and Viewer from OpenAPI, the Swagger Editor
  • Can be installed via npm or run via docker
  • PRO - from OpenAPI, the maintainer of Swagger
  • PRO - seemed to have some helpful hints
  • it is possible that the above-mentioned VS Code extension could do the same but I haven't used it enough
  • CON - the editor is not as nice as working in VS Code
  • CON - the editor is running in a web browser
• Viewer only from OpenAPI, the official Swagger UI
  • This will be helpful for just wanting to use the API and not document
  • Can be installed via npm or run via docker, install/setup link

[MicahWW]

There are 3 versions of the specification, 2, 3, and 3.1. As the swagger editor doesn't currently fully sport the 3.1 specification, I think the best option is to stay with version 3. The latest of which is 3.0.3

Documentation for 3.0.3

[MicahWW]

The process has been started but there is much to go. At this point though individual issues will be brought up for issues found, better documentation, etc..

The different links mentioned here have also been quoted in the readme as of 1fc3551