Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document the endpoints using OpenAPI 3.0 #4

Open
15 of 22 tasks
aabounegm opened this issue Dec 11, 2019 · 0 comments · Fixed by #150
Open
15 of 22 tasks

Document the endpoints using OpenAPI 3.0 #4

aabounegm opened this issue Dec 11, 2019 · 0 comments · Fixed by #150
Labels
documentation Improvements or additions to documentation postponed Postponed for a better time

Comments

@aabounegm
Copy link
Member

aabounegm commented Dec 11, 2019 •
edited
Loading

Document the API endpoints using OpenAPI 3.0 so that it can generate Swagger (or similar) documentation.

views:

  • product
  • variety
  • project
  • activity
  • account
  • application
  • notification

Models:

  • product
  • variety
  • project
  • activity
  • account
  • application
  • notification
  • Separate schemas for request and response (or use readOnly and writeOnly)

Security:

  • Specify permissions (admin, user, project moderator, project creator)

other:

  • more descriptive response descriptions and summaries
  • use operationIds that coincide with the function name in the Flask code
  • use descriptions from the endpoints' docstring
  • use x-tagGroups for Redoc grouping
  • document the different responses for the same response code (using oneOf. Ex: multiple possible error messages for the code 400)
  • Add externalDocs that point to Notion pages
@aabounegm aabounegm added the documentation Improvements or additions to documentation label Dec 11, 2019
@aabounegm aabounegm self-assigned this Dec 11, 2019
@aabounegm aabounegm added this to the Initial Release milestone Jan 5, 2020
@aabounegm aabounegm mentioned this issue Jun 20, 2020
Merged
@illright illright removed this from the Initial Release milestone Jul 4, 2020
@illright illright added the postponed Postponed for a better time label Jul 7, 2020
@illright illright reopened this Jul 7, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation Improvements or additions to documentation postponed Postponed for a better time
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Swagger docs Innopoints/backend
2 participants
@aabounegm @illright