Developing ONAP API Documentation

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: https://lf-onap.atlassian.net/browse/REQ-386

JIRA Epic: https://lf-onap.atlassian.net/browse/DOC-608

  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/
    https://lf-onap.atlassian.net/browse/DOC-609

  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

  • Use Swagger toolset to develop and publish Swagger / OpenAPI 3.0 API Specs (in JSON or YAML) (e.g., SwaggerHub)

  • 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

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

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

API Validation Tool Candidates 

Existing ONAP Documentation



ONAP API Analysis

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

ONAP Project

API Name

Lines / EP Operations

Style Findings

Notes

Swagger Link

External API

Service Catalog

798 / 3

Easy to apply ONAP Style Guide. Still need examples

Based on TMF

[externalapi/nbi.git] / docs / offeredapis / api_serviceCatalog /

AAI

AAI

66685/ 1383

Very Large. Some examples. Lots of descriptions. Need to update generation functionality to support style.

Generated from OXM

[aai/aai-service.git] / aai-schema / src / main / resources / oxm /

AAI REST API Documentation - Frankfurt

SDC

Distribution & External

4684 / 22

Some missing descriptions. No examples

Lots of modeling work around SDC

[sdc.git] / docs / swagger /

SO

SO Regular

2303 / 53

No descriptions or examples



[so.git] / docs / api / swagger /

SO

SO Monitoring

467 / 6

No descriptions or examples. Small & easy to fix



[so.git] / docs / api / swagger /

SDN-C

Generic Resource

108809 / 1947

HUGE. Some descriptions. No examples

Made the linter choke. Needs modularization

[sdnc/northbound.git] / generic-resource-api / model / src / main / resources /

DCAE

VES Collector

928 / 20

No examples, very few descriptions

Interest from 3GPP

[dcaegen2/platform/inventory-api.git] /

DCAE

Inventory

697 / 9

Lots of descriptions, even in schema! No examples



[dcaegen2/collectors/ves.git] / 

Policy

Policy API

906 / 8

Lots of descriptions! No examples

Nice & modular

[policy/parent.git] / docs / api / swagger /