Page Comparison

...

• 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

  • See: snackswag.json for an example of the markdown embedded in the Swagger file

    • Note: the MD file inside the swagger replaces the newlines with "\n"

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

  • See: ExtAPI Meeting Notes

...