2020-03-27 API Docs Meeting Notes

Owned by Andy Mayer
Last updated: Mar 27, 2020Version comment
1 min read

Date: 

Mar 27, 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 OSullivan@Andy 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: (e.g., Minimum 1, 2, & 3 Guilin; 4 & 5 Stretch goals)

      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 HTML in Readthedocs for the release.

      3. Apply Minimum (Phase 1+) swagger guidelines

        1. Use common insert for Info section template

      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 (plan to present to TSC on April 9th)

    • 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: