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

...

• 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: 

Jira Legacy
server System Jira columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 4733707d-2057-3a0f-ae5e-4fd8aff50176 key REQ-386

JIRA Epic: 

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/
   

   Jira Legacy
   server System Jira columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 4733707d-2057-3a0f-ae5e-4fd8aff50176 key DOC-609

2. Apply ReDoc to Swagger and place HTML in Readthedocs for the release
   

   Jira Legacy
   server System Jira columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 4733707d-2057-3a0f-ae5e-4fd8aff50176 key DOC-610

3. Apply Minimum (Phase 1+) swagger guidelines
   

   Jira Legacy
   server System Jira columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 4733707d-2057-3a0f-ae5e-4fd8aff50176 key DOC-611

   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:

 

View file
name Documenting ONAP APIs OCT2019.pptx height 150

...

• 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

Image Added

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.