2020-03-27 API Docs Meeting Notes

Date: 

27 Mar 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: 
• Introduction (Andy Mayer)
• Review of progress
• External API status Adrian OSullivanAndy Mayer
• Phasing of recommended Style Elements Andy Mayer Adrian OSullivan Seshu Kumar Mudiganti
  • Proposed Phase 1+ OpenAPI 2.0 / Swagger Style Guide
  • Once we agree, will define associated Spectral Ruleset
  • Phased activities:
    1. All components should place externally facing API definitions (e.g. Swagger) in a common path within their Gerrit/Git 
       1. Suggested Path: <Component>/docs/api/swagger/
    2. Apply ReDoc to Swagger and place UML in Readthedocs for the release.
    3. Apply Minimum (Phase 1) swagger guidelines
    4. Use embedded markdown for conceptual documentation
    5. Apply full swagger guidelines.
• Discussion new effort on enhancing SO APIs. (Andy Mayer Seshu Kumar Mudiganti)
• Preparation of readout to PLTs and TSC
  • The big picture
  • Example from External API (before and after)
  • Start smaller
    • Placement of Swagger files in Gerrit/Git
    • Use of Redoc for API documentation
    • Application of Phase 1 Style
    • Tools that are available 

Future Topics

Identify ONAP APIs that are not using Swagger / OpenAPI

Automate publishing Swagger in ReadTheDoc (Eric Debeau) Matthieu Geerebaert

Possible recommendation for use of SwaggerHub, need proposal slide deck

Explore API Catalog / Library Tools

Zoom Chat Log from Meeting: