Style Guide for defining APIs in Swagger / OpenAPI 3.0
- See: Proposed OpenAPI 2.0 / Swagger Style Guide
Use Swagger toolset to develop and publish Swagger / OpenAPI 3.0 API Specs (in JSON or YAML) (e.g., SwaggerHub)
- See: API Style Validation Tool
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)
- For an example of the HTML file generated by Redoc, See: SnackSwag.html
- For best viewing: Download both the logo.png file and the SnackSwag.html file to the same directory, then open locally.
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
- See: Conceptual API Documentation Structure
Select and work with a few ONAP projects to pilot the approach for Frankfurt (e.g., External API, SO, etc.)
- See: ExtAPI Meeting Notes

Note: Need to explore placing OpenAPI files (.json or .yaml) into a common directory in each project's Repo.

Proposed Documentation Tooling Flow

Image Added

...