In GitLab by @infinitewarp on Apr 9, 2019, 14:16

Summary

As a good neighbor developer in the Insights platform, I want cloudigrade's v2 APIs to implement the OpenAPI spec because this is required by Red Hat Insights Platform
[IPP-12] Customer-Facing REST API Design Guidelines

This story addresses the following three MUSTs from IPP-12 (as of 2019-04-09):

All customer-facing APIs built inside the Insights Platform MUST be described via an OpenAPI version 3 specification.

...

For consistency and to support automated testing of APIs, all applications MUST serve the current OpenAPI specification in JSON format on $PATH_PREFIX/$APP/v$VERSION/openapi.json.

To facilitate automated testing of APIs, all operations MUST have an operationId defined. For more information, please see OpenAPI: Paths and Operations.

Acceptance Criteria

• Verify the OpenAPI specification is served at v2/openapi.json
  • includes the DRF API routes defined in failure to save instance if image not accessible at clount creation #525
  • includes the sysconfig route defined in Remove old Djoser-based authentication #523
  • every operation has a unique operationId
• Verify that we have removed the v2-relevant examples and code from the API REST examples doc.
  • This is not strictly necessary, and the examples are still useful to see.

Assumptions and Questions

• The specification only needs to include v2 APIs. We do not need a specification for v1.
• When we port/rebuild the report APIs, each one we add to v2 must include updates to support the OpenAPI spec we build here.
• The official OpenAPI spec defined: https://github.com/OAI/OpenAPI-Specification/
• a popular OpenAPI generator, maybe useful for reference: https://github.com/OpenAPITools/openapi-generator
• IPP-12 has a related SHOULD section, but there is an unresolved discussion in the sidebar about whether or not this makes sense:

  All OpenAPI specifications SHOULD maintain this specification file in its VCS repository alongside the code that it describes. The specification file SHOULD NOT be auto-generated in response to code changes.

• This means we can stop updating and start deleting our manually-made API REST examples doc as soon as Periodically check that customer's Cloud Account is still good #553 is done.
• No immediate code changes for QE+integrade, but we should have QE sanity-check our work at least once manually and check the ACs.
• See also this issue (and related ones) on DRF: Added OpenAPI Schema Generation. encode/django-rest-framework#6532
• See also this release milestone: https://github.com/encode/django-rest-framework/milestone/69