2019-10-18 API Docs Meeting Notes

Date: 

Oct 18, 2019 

Meeting Link: https://zoom.us/j/731954210

Agenda / Discussed:

• RECORD: zoom_0.mp4

• Kickoff (@Andy Mayer)

• Approach

  • Style Guide for defining APIs in Swagger (& OpenAPI 3.0)

  • Recommend Swagger toolset to develop, validate and publish Swagger / OpenAPI 3.0 API Specs (in JSON or YAML) (e.g., SwaggerHub)

  • Select a tool for generation of API Reference documentation directly from Swagger / OpenAPI files (using Redoc for example which creates a consistent standalone HTML file)

  • Create common and uniform Conceptual API Documentation describing each API and provides quick start and usable TIFY(try it for yourself) samples

    • Start with a common ONAP RST template, instructions, and examples

  • Select and work with a few ONAP projects to pilot the approach for Frankfurt (e.g., External API, SO, etc.)

• Style Guide Discussion (@Andy Mayer)

• API Reference Document Generation Tools (@Eric Debeau @Matthieu Geerebaert )

Future Topics

Identify ONAP APIs that are not using Swagger / OpenAPI

Style Guide Review (@Andy Mayer)

Automate publishing Swagger in ReadTheDoc (@Eric Debeau) @Matthieu Geerebaert

Recommendation for use of SwaggerHub, need proposal slide deck

Zoom Chat Log from Meeting: