Dear ONAP PTLs: We are holding a virtual meeting tomorrow to go over REQ-386: Apply common Swagger style and documentation generation tools to create robust ONAP API documentation. See: https://jira.onap.org/browse/REQ-386 The meeting is scheduled for 9:00am-10:00am eastern US (13:00-14:00 UTC) on https://zoom.us/j/731954210 See: https://lists.onap.org/g/onap-modelingsub/viewevent?repeatid=18373&eventid=860845&calstart=2020-08-14
We simplified REQ-386 by focusing on two items: Required 1: We are asking that each project place their exposed API definitions in a common path structure inside Git/Gerrit: <Component>/docs/api/swagger/ Required 2: When the API definitions for the project are stable and ready to be documented, we are asking that each project use Redoc to produce an HTML version of the Swagger API definition See: https://wiki.onap.org/display/DW/Using+Redoc+to+Generate+API+Reference+Documentation We will have the remaining items as stretch goals for Guilin (this lets us phase in better API documentation): Stretch Goal 1: We are expecting each project to adhere to the simplified "Phase 1+ OpenAPI Style guide" See: https://wiki.onap.org/pages/viewpage.action?pageId=81397461 We greatly simplified the required elements of the style guide to focus on some very simple updates to the info sections, versioning, and essential Swagger elements. Stretch Goal 2: We are using a linter called Spectral. I am currently working on an updated ruleset for the simplified version of the style guide. Also, Eric Debeau<https://jira.onap.org/secure/ViewProfile.jspa?name=eric.debeau> is exploring ways to integrate Spectral as part of the ONAP CI process. For more information on Spectral please see: https://wiki.onap.org/display/DW/API+Style+Validation+Tool Please join the Zoom meeting if you have any questions or would like to discuss the details around this non-functional requirement. Best Regards, Andy Andy Mayer, Ph.D. | PMTS, Network Cloud and Infrastructure | AT&T Labs | Phone: +1 (732) 420-9945 | am8...@att.com<mailto:am8...@att.com> [cid:image001.jpg@01D2E10C.0410C230] -=-=-=-=-=-=-=-=-=-=-=- Links: You receive all messages sent to this group. View/Reply Online (#21902): https://lists.onap.org/g/onap-discuss/message/21902 Mute This Topic: https://lists.onap.org/mt/76174129/21656 Group Owner: onap-discuss+ow...@lists.onap.org Unsubscribe: https://lists.onap.org/g/onap-discuss/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
