Add OpenAPI for curator service api #226
Conversation
I guess we should? I'm guessing they'll have the flexibility to diverge at a certain point, as each service becomes more tailored to its individual purpose. But we don't have to do it now. @axmb WDYT |
| put: | ||
| summary: Updates a specific user's roles | ||
| operationId: updateUser | ||
| requestBody: |
There was a problem hiding this comment.
it looks like the body of this request is currently a list of roles, not the whole user obj: https://github.com/open-covid-data/healthmap-gdo-temp/blob/master/verification/curator-service/api/src/controllers/users.ts#L58
There was a problem hiding this comment.
Ah yea I was thinking it's possible to pass the whole user object, and we'll only access the roles field. But it's worth making it explicit that roles is the only field we're using. Done.
It should probably be documented, so that the OpenAPI page is a complete list of endpoints provided by the service. I don't think it has to be done now, either. Perhaps there's a simple way to create a section for this, and say "see <:3000/api/docs>" until they actually diverge. |
The swagger docs say you can use a $ref for a path: And the $ref docs say you can use a relative path to another yaml file: But there is a bug in openapi v3 that relative paths aren't working: swagger-api/swagger-editor#1409 That bug was assigned to someone 12 days ago, so maybe they'll make some progress there. I'll wait to see if there are any updates there and add the ref for cases here if it gets fixed. |
I wasn't sure whether or not to add /cases to the yaml, since it is already documented/verified in the data-service OpenAPI. I refrained for now, but let me know if you think it would be useful to add here as well.