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:
View file name Developing ONAP API Documentation APR2020.pptx height 150
Non-Functional Requirement for Guilin: Jira server ONAP JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 425b2b0a-557c-3c0c-b515-579789cceedb key REQ-386
server | ONAP JIRA |
---|---|
columns | key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution |
serverId | 425b2b0a-557c-3c0c-b515-579789cceedb |
key | REQ-386 |
JIRA Epic: Jira server ONAP JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 425b2b0a-557c-3c0c-b515-579789cceedb key 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/Jira server ONAP JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 425b2b0a-557c-3c0c-b515-579789cceedb key DOC-609 - Apply ReDoc to Swagger and place HTML in Readthedocs for the release
Jira server ONAP JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 425b2b0a-557c-3c0c-b515-579789cceedb key DOC-610 Apply Minimum (Phase 1+) swagger guidelines
Jira server ONAP JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 425b2b0a-557c-3c0c-b515-579789cceedb key DOC-611 - See: Proposed Phase 1+ OpenAPI 2.0 / Swagger Style Guide
- 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
name | Documenting ONAP APIs OCT2019.pptx |
---|---|
height | 150 |
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: 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
FrankfortFrankfurt (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
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 | [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 |