Hi Andy, I went through some of the python libraries which can automatically generate and embed API docs into read the docs. The following seems to be a feasible solution. We are already using sphinxcontrib in the read the docs, it should be easy to integrate. Let me try it out once and let you know about it.
https://sphinxcontrib-redoc.readthedocs.io/en/stable/ With best regards Krishna ________________________________ From: onap-discuss@lists.onap.org <onap-discuss@lists.onap.org> on behalf of Andy Mayer via lists.onap.org <am803u=att....@lists.onap.org> Sent: Friday, August 14, 2020 12:39 AM To: onap-discuss@lists.onap.org <onap-discuss@lists.onap.org> Cc: onap-modeling...@lists.onap.org <onap-modeling...@lists.onap.org> Subject: [onap-discuss] Documenting ONAP APIs in Guilin: REQ-386 ** This mail has been sent from an external source. Treat hyperlinks and attachments in this email with caution** 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<https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fjira.onap.org%2Fbrowse%2FREQ-386&data=02%7C01%7Ckrishna.moorthy6%40wipro.com%7C0f186b6f2b9f430eeec308d83fbc7181%7C258ac4e4146a411e9dc879a9e12fd6da%7C1%7C1%7C637329425882099965&sdata=dYFtlVy4UnofbiPOUPWhsQ7z%2FpdZLRpsZyTwzz83A7E%3D&reserved=0> The meeting is scheduled for 9:00am-10:00am eastern US (13:00-14:00 UTC) on https://zoom.us/j/731954210<https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fzoom.us%2Fj%2F731954210&data=02%7C01%7Ckrishna.moorthy6%40wipro.com%7C0f186b6f2b9f430eeec308d83fbc7181%7C258ac4e4146a411e9dc879a9e12fd6da%7C1%7C0%7C637329425882099965&sdata=wKsKoMucCL8%2FwHGmK1COAzpB0kdhJJP%2Fepf8rC%2BgyDU%3D&reserved=0> See: https://lists.onap.org/g/onap-modelingsub/viewevent?repeatid=18373&eventid=860845&calstart=2020-08-14<https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.onap.org%2Fg%2Fonap-modelingsub%2Fviewevent%3Frepeatid%3D18373%26eventid%3D860845%26calstart%3D2020-08-14&data=02%7C01%7Ckrishna.moorthy6%40wipro.com%7C0f186b6f2b9f430eeec308d83fbc7181%7C258ac4e4146a411e9dc879a9e12fd6da%7C1%7C0%7C637329425882109960&sdata=HGLh8VKJxsgaGXSMW8s7FIhJRGuwABDWMexQZL6zsbI%3D&reserved=0> 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<https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.onap.org%2Fdisplay%2FDW%2FUsing%2BRedoc%2Bto%2BGenerate%2BAPI%2BReference%2BDocumentation&data=02%7C01%7Ckrishna.moorthy6%40wipro.com%7C0f186b6f2b9f430eeec308d83fbc7181%7C258ac4e4146a411e9dc879a9e12fd6da%7C1%7C1%7C637329425882109960&sdata=gXqc2T2BGTHEV1aV5IB6mzdw2i6K%2FGDP6k1g68d9ObA%3D&reserved=0> 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<https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.onap.org%2Fpages%2Fviewpage.action%3FpageId%3D81397461&data=02%7C01%7Ckrishna.moorthy6%40wipro.com%7C0f186b6f2b9f430eeec308d83fbc7181%7C258ac4e4146a411e9dc879a9e12fd6da%7C1%7C1%7C637329425882119950&sdata=C5lpD9Xs4ddj2Q2BH696PQb2mH8%2FRu9nYxE8SfMCjX4%3D&reserved=0> 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://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fjira.onap.org%2Fsecure%2FViewProfile.jspa%3Fname%3Deric.debeau&data=02%7C01%7Ckrishna.moorthy6%40wipro.com%7C0f186b6f2b9f430eeec308d83fbc7181%7C258ac4e4146a411e9dc879a9e12fd6da%7C1%7C1%7C637329425882119950&sdata=mwb74M7YMoHrkWiQ%2FIherQJQPKw%2BPf%2B36rHLeItbPe4%3D&reserved=0> 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<https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.onap.org%2Fdisplay%2FDW%2FAPI%2BStyle%2BValidation%2BTool&data=02%7C01%7Ckrishna.moorthy6%40wipro.com%7C0f186b6f2b9f430eeec308d83fbc7181%7C258ac4e4146a411e9dc879a9e12fd6da%7C1%7C1%7C637329425882129946&sdata=6O5Bf5x39dM75Pd4qeycYLxoahY2URSTE64gM4eaPUM%3D&reserved=0> 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] The information contained in this electronic message and any attachments to this message are intended for the exclusive use of the addressee(s) and may contain proprietary, confidential or privileged information. If you are not the intended recipient, you should not disseminate, distribute or copy this e-mail. Please notify the sender immediately and destroy all copies of this message and any attachments. WARNING: Computer viruses can be transmitted via email. The recipient should check this email and any attachments for the presence of viruses. The company accepts no liability for any damage caused by any virus transmitted by this email. www.wipro.com -=-=-=-=-=-=-=-=-=-=-=- Links: You receive all messages sent to this group. View/Reply Online (#21916): https://lists.onap.org/g/onap-discuss/message/21916 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] -=-=-=-=-=-=-=-=-=-=-=-
