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

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

Calendar-Meeting-Invite.ics

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)
• Eric Debeau (Documentation Project)

For Proposal Please See:

Proposed ACTION: Create non-functional requirements for Guilin release:

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/
2. Apply ReDoc to Swagger and place HTML in Readthedocs for the release

3. Apply Minimum (Phase 1+) swagger guidelines

   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

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

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.