When: Web meetings monthly on Friday at 10:00am (Eastern US)

Zoom Bridge: https://zoom.us/j/731954210

Goal: Development and Documentation Go Hand-in-hand

• From Writing API Documentation -> Developing API Documentation

• Make it easy to create by designers and developers

• Make it easy to access and relevant to developers

  • Developer engagement

• Make it easy to use: Sample Calls and Code are essential

  • Try It For Yourself (TIFY) Examples

  • Panes on page with prose, sample code, and navigation / search

  • Keep simple and easy to understand

  • Copy and paste friendly

  • Target languages (and code generation)

Team (please add your name below to sign up)

• @Andy Mayer (Modeling Subcommittee)

• @Timo Perala  (Documentation Project)

• @Matthieu Geerebaert (External API Project)

• @Adrian OSullivan (External API Project)

• @Eric Debeau (Documentation Project)

For Proposal Please See:

Non-Functional Requirement for Guilin: REQ-386: Apply common Swagger style and documentation generation tools to create robust ONAP API documentationDone

JIRA Epic: DOC-608: Apply common Swagger style and documentation generation tools to create robust ONAP API documentationClosed

1. All components should place externally facing (i.e. interfaces exposed by the ONAP component to either other ONAP components or components external to ONAP) API definitions (e.g. Swagger) in a common path within their Gerrit/Git 
   Suggested Path: <Component>/docs/api/swagger/
   DOC-609: Placement of Swagger files in Gerrit/GitClosed

2. Apply ReDoc to Swagger and place HTML in Readthedocs for the release
   DOC-610: Apply ReDoc to produce Swagger documentationClosed

3. Apply Minimum (Phase 1+) swagger guidelines
   DOC-611: Apply Minimum (Phase 1+) Swagger guidelinesClosed

   1. See: Proposed Phase 1+ OpenAPI 2.0 / Swagger Style Guide

   2. Use the common insert for the info section (e.g., license info, contact info, etc): Swagger Insert Sample for Info Section

For Background Please See:

The API Documentation Factory

Open

Approach and Steps

Modeling Subcommittee along with the Documentation Project will discuss and recommend to the TSC a common API Documentation approach for ONAP.

• 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

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

Proposed Documentation Tooling Flow

Open

Reference Documentation Generation Tool Candidates

• Swagger2Doc: https://github.com/openconnectivityfoundation/swagger2doc

  • No more maintained. Do not cover full OpenAPI specifications

• Swagger Codegen: https://github.com/swagger-api/swagger-codegen

• Swagger UI: https://github.com/swagger-api/swagger-ui

• Redoc: https://github.com/Redocly/redoc

• Spectacle: https://sourcey.com/spectacle

API Validation Tool Candidates 

• Spectral: https://github.com/stoplightio/spectral

  • See: API Style Validation Tool

• From Visual Studio OSM: https://github.com/felipevicens/osm-visualstudio-extension

Existing ONAP Documentation

• https://docs.onap.org/en/elalto/guides/onap-developer/how-to-use-docs/api-swagger-guide.html

ONAP API Analysis

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