Add Documentation to API
Closed this issue · 0 comments
Intro
In order to keep track of the API routes, we use a library called Swagger to auto-document the api based on the Open API specification. Open API aims to standardize REST API specifications, and has libraries in most web frameworks/libraries - including Express (Node.js) and Django (Python). Swagger seeks to build on top of this specification to create a user interface for displaying and testing apis, going as far as creating a way to test API calls within the documentation page itself. Here is what part of our page looks like:
I spent a while trying to figure out how to get Swagger to automatically register API responses so it would be easier to see what routes return what (makes frontend devs' jobs a lot easier), but the only method I found requires a substantial refactor. Instead, for now at least, I figured we should manually tell swagger what object types are returned. In the distant future we will probably refactor the server to NestJS, which (I'm pretty sure) takes care of this automatically.
Goals
Each route should contain information about what is required as input, and what shape the output is. Here is an example of the create group route:
Tasks
NOTE: You must be authenticated to test the apis with a padlock, read this for information about user auth: User Authentication WIKI
Group Routes
- Response code 200 for group spotify management
- Response code 200 for group CRUD ops (create, list, get, update, delete)
- Request data for any group post, put, patch routes
User Routes
- Response code 200 for user management routes
- Response code 200 for user CRUD ops (create, list, get, update, delete)
- Request data for any user post, put, patch routes
Resources
More Info...
- Swagger Autogen (Generates OpenAPI schemas)
- Swagger UI Express (Used for creating the actual html page)