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:
View file name Developing ONAP API Documentation APR2020.pptx height 150
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
| 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: 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-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 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 - 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 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 - 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 |
...
Proposed Documentation Tooling Flow
Reference Documentation Generation Tool Candidates
...
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 |