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
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-609Apply ReDoc to Swagger and place HTML in Readthedocs for the release
Apply Minimum (Phase 1+) swagger guidelines
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
Start with a common ONAP RST template, instructions, and examples
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
Spectacle: https://sourcey.com/spectacle
API Validation Tool Candidates
Spectral: https://github.com/stoplightio/spectral
From Visual Studio OSM: https://github.com/felipevicens/osm-visualstudio-extension
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 / |
SDC | Distribution & External | 4684 / 22 | Some missing descriptions. No examples | Lots of modeling work around SDC | |
SO | SO Regular | 2303 / 53 | No descriptions or examples | ||
SO | SO Monitoring | 467 / 6 | No descriptions or examples. Small & easy to fix | ||
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 | |
DCAE | Inventory | 697 / 9 | Lots of descriptions, even in schema! No examples | ||
Policy | Policy API | 906 / 8 | Lots of descriptions! No examples | Nice & modular | [policy/parent.git] / docs / api / swagger / |