Skip to content
This repository has been archived by the owner on Sep 2, 2024. It is now read-only.

Revisit API documentation template to reduce redundancy #164

Closed
shilpa-padgaonkar opened this issue Mar 3, 2023 · 19 comments
Closed

Revisit API documentation template to reduce redundancy #164

shilpa-padgaonkar opened this issue Mar 3, 2023 · 19 comments
Assignees
@jordonezlucena
Labels
commonalities

Comments

@shilpa-padgaonkar
Copy link
Contributor

Currently, a lot of information for the API spec file is duplicated in the API documentation. This results in huge efforts even when making very small, insignificant changes to the API as we need to duplicate the information back to the API documentation.
With this issue, the suggestion is to have no/very minimum redundant information as a part of the API documentation that is already a part of the spec file.
@jordonezlucena
Copy link
Contributor

Hi Shilpa, any concrete proposal to move discussion forward?

@jordonezlucena jordonezlucena self-assigned this Mar 7, 2023
@shilpa-padgaonkar
Copy link
Contributor Author

@jordonezlucena :
I would propose to not have the errors section in the doc. This is already a part of the spec file
Also, for the endpoint definition section, we should only include the things which are not already a part of the spec.
The intention is to have the spec file as the main source of truth and the document is more supplementary for eg. to provide FAQs, general overview, code snippets etc.

@shilpa-padgaonkar
Copy link
Contributor Author

Approach seems to be ok. We need to provide a sample api spec which is more complete as part of this issue/pr to set an example.

@eric-murray
Copy link
Contributor

My proposal would be not to have separate documentation at all, but to embed all documentation within the OAS (Swagger) definition itself. The Swagger Editor (an open source project) can then be used as the "documentation viewer". Sub projects can add as much or as little additional documentation within the OAS definition file as preferred without the overhead of needing to update separate documentation when the OAS definition is updated.

The Swagger editor appears to render both markdown and HTML are supported to some extent, though doesn't appear very well documented what exactly is supported, so might need some trial an error. Images and other external documents can be inline linked with a bit of patience.

@shilpa-padgaonkar
Copy link
Contributor Author

Even better! I suggested a mellow approach to start with expecting it might not go down that well :)

@jlurien
Copy link

jlurien commented Mar 8, 2023

Redocly/redoc is also a very popular and powerful viewer for OpenAPI specs: https://redocly.com/redoc/, demo: https://redocly.github.io/redoc/

jlurien added a commit to jlurien/QualityOnDemand that referenced this issue Mar 9, 2023
@jlurien
Rename properties to new terms
71512bc 
- Applied lowerCamelCase for property names, UpperCamelCase for schema names
- Updated API_documentation as well. This is a redundant effort that hopefully we don't have to maintain in the future, as being discussed in camaraproject/WorkingGroups#164
- In a separate PR we should enhance descriptions, once Glossary definitions are consolidated.
@jlurien jlurien mentioned this issue Mar 9, 2023
Merged
@shilpa-padgaonkar
Copy link
Contributor Author

shilpa-padgaonkar commented Mar 11, 2023 •
edited
Loading

As discussed in the commonalities meeting, at least 2 subprojects can nominate themselves to provide the improved version of their spec files as showcases.
Request the subproject members to drop a comment under this issue if they would like to participate.

@jpengar jpengar mentioned this issue Mar 13, 2023
Closed
@shilpa-padgaonkar
Copy link
Contributor Author

shilpa-padgaonkar commented Mar 21, 2023 •
edited
Loading

If we have no nominations until the commonalities call on Thursday 23rd Mar, we might have to restrict the scope of this issue to updating the API documentation template. The template will include a new comment under sections Errors and Endpoints that this information should be a part of the AP spec file.

@jordonezlucena
Copy link
Contributor

Telefonica agrees on updating API documentation template as noted above.
Telefonica also volunteers to provide the improved versions as showcases for HomeDevicesQoD Sub-Project

@jordonezlucena
Copy link
Contributor

Telefonica agrees on updating API documentation template as noted above.
Telefonica also volunteers to provide the improved versions as showcases for HomeDevicesQoD Sub-Project

Here's the example: https://github.com/camaraproject/HomeDevicesQoD/blob/main/code/API_definitions/home_devices_qod.yaml. As you may notice, it is self-contained, as demanded in this issue. We propose this YAML can be used as example, mirrored accordingly for the rest of APIs.

@bigludo7
Copy link
Contributor

One question: is it possible to embed in the OAS description: part .jpg or .png ? For some API we need to provide sequence diagram to explicit resource use (like number verification) or to provide state engine (like for carrier billing).
If it is possible I'm fine with your proposal - if not that could be a problem for me to not have anymore the md doc.

@eric-murray
Copy link
Contributor

@bigludo7
Images can be inline linked using HTML. If the images are stored in the github, then using an absolute rather than relative URL should allow the image still to be rendered given only the OAS file itself, so long as the viewer also has an internet connection.
https://spec.commonmark.org/0.27/#images

@PedroDiez PedroDiez mentioned this issue Apr 20, 2023
Closed
@PedroDiez
Copy link
Contributor

Regarding the linking of images, it has been tested within fake PR (to be closed) within Carrier Billing WG.
For your convenience: camaraproject/CarrierBillingCheckOut#70

Model applied: ![image_ref_name]($full_link?raw=true)

Thanks @eric-murray for providing the clue.
Yesterday within WG CB meeting, we comment about this cc @bigludo7

@PedroDiez
Copy link
Contributor

@shilpa-padgaonkar , @jordonezlucena What do you think about this topic?

Honestly speaking, think we are in the conditions to apply this guidance in every WG

@jordonezlucena
Copy link
Contributor

Yes, ok for me. The API owner of each Sub-project shall open a PR to apply this.

@eric-murray eric-murray mentioned this issue Apr 28, 2023
Closed
@shilpa-padgaonkar
Copy link
Contributor Author

/LGTM, Agree with Jose about subprojects creating relevant issue and PR.

@hdamker hdamker mentioned this issue May 5, 2023
Closed
@jpengar jpengar mentioned this issue May 23, 2023
Merged
@shilpa-padgaonkar
Copy link
Contributor Author

With the proposal being accepted and relevant PRs in subproject being created, can we close this issue in commonalities?

@jordonezlucena
Copy link
Contributor

jordonezlucena commented Jun 1, 2023 •
edited
Loading

Agree with Shilpa's proposal.
However, all of us need to ensure this is applied to every sub-project.

@shilpa-padgaonkar
Copy link
Contributor Author

Based on the discussion in commonalities call on 01.06, this issue can now be closed.

@monamok monamok mentioned this issue Jun 5, 2023
Closed
This was referenced Jun 5, 2023
Merged
Closed
@akoshunyadi akoshunyadi mentioned this issue Jun 22, 2023
Closed
@PedroDiez PedroDiez mentioned this issue Jun 23, 2023
Closed
@hdamker hdamker mentioned this issue Sep 1, 2023
Closed
@rartych rartych mentioned this issue Jul 31, 2024
Merged
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@jordonezlucena jordonezlucena

Labels
commonalities
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@jlurien @PedroDiez @bigludo7 @shilpa-padgaonkar @eric-murray @jordonezlucena