2020-08-14 API Docs Meeting Notes
- Andy Mayer
Date:
Aug 14, 2020 at 9:00AM EST (US Eastern)
Note new time is 9:00AM Eastern US.
Meeting Link: https://zoom.us/j/731954210
Agenda / Discussed:
RECORD: zoom_0.mp4
Introduction (@Andy Mayer)
Review of REQ-386: REQ-386: Apply common Swagger style and documentation generation tools to create robust ONAP API documentationDone
We simplified REQ-386 by focusing on two items:
Required 1: We are asking that each project place their exposed API definitions in a common path structure inside Git/Gerrit:
<Component>/docs/api/swagger/
Required 2: When the API definitions for the project are stable and ready to be documented, we are asking that each project use Redoc to produce an HTML version of the Swagger API definition
See: https://lf-onap.atlassian.net/wiki/display/DW/Using+Redoc+to+Generate+API+Reference+Documentation
We will have the remaining items as stretch goals for Guilin (this lets us phase in better API documentation):
Stretch Goal 1: We are expecting each project to adhere to the simplified "Phase 1+ OpenAPI Style guide" See: https://lf-onap.atlassian.net/wiki/pages/viewpage.action?pageId=16413461
We greatly simplified the required elements of the style guide to focus on some very simple updates to the info sections, versioning, and essential Swagger elements.
Stretch Goal 2: We are using a linter called Spectral. I am currently working on an updated ruleset for the simplified version of the style guide. Also, Eric Debeau is exploring ways to integrate Spectral as part of the ONAP CI process.
For more information on Spectral please see: https://lf-onap.atlassian.net/wiki/display/DW/API+Style+Validation+Tool
Future Topics
Automate publishing Swagger in ReadTheDoc (@Eric Debeau) @Matthieu Geerebaert @krishna moorthy
Simplified Spectral Ruleset @Andy Mayer