API Documentation

[FabrizioMoggio]

Considering the following PR:

#35

And the related Discussion/Issue:

#34

My understanding is that there is a new approach for the API documentation. Having all documented in the YAML file without producing a specific Api_documentatoin.md file.

I still have some doubts on:

1. How to manage the current .md files, for the APIs that already have an API_Documumentation.md file, what do we need to do? Do we continue to maintain and update it, we delete it and we include all the documentation in the current YAML or we delete it when a new YAML version is released?

2. I also have a doubt on what to include in the YAML as documentation. Is it still what it is defined in the documentation template as defined in the Wiki (Commonalities WG - CAMARA Project - Confluence)

https://github.com/camaraproject/Commonalities/blob/main/documentation/API-DocumentationTemplate.md

[hdamker]

@FabrizioMoggio Here is how we did it in QoD: https://github.com/camaraproject/QualityOnDemand/pull/151/files
Moved the markdown content into the YAML file and deleted the previous *.md file.

Within the release before this change (v0.8.1) the "deleted" API documentation file is still there: https://github.com/camaraproject/QualityOnDemand/blob/release-0.8.1/documentation/API_documentation/QoD_API.md

In the releases after the PR the documentation is now inline within the YAML and can be nicely read with tools like Swagger Editor and Redoc, e.g. now for v0.10.1:

• View it on ReDoc
• View it on Swagger Editor
• OpenAPI YAML spec file

We have still some documentation within the API_documentation directory, like the QoSProfile_Mapping_Table.md which is referenced from the YAML file.

Regarding https://github.com/camaraproject/Commonalities/blob/main/documentation/API-DocumentationTemplate.md: from my perspective not any more relevant, at least not completely. There is for example no need any more to list the Endpoints and Errors, as they are anyway in the YAML, we copied only the descriptions into the right places.

Hope that helps a bit.

[FabrizioMoggio]

@hdamker thank you this helps very much. For the TI API we actually always had the documentation inside the YAML and in the "API_documentation.md" file. We used indeed a tool to create the documentation from the YAML.

Regarding API-DocumentationTemplate.md, it was helpful to create a common documentation structure across the different CAMAR APIs, so I think that, for a new API developer, having that information is still relevant. For sure some section is no more needed because it is already in the YAML, as you said, and for sure it must be clear that the documentation is not required in a specific external .md file but it must be inside the YAML itself. So I'm wondering if that information should go to the API Development Guidelines (https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md) or it is anyway better to have a specific file to explain how to document a YAML. If we go for the second option (keeping a specific file), it needs for sure an update to:

• specify that the documentation is in the YAML.
• remove the unnecessary sections

About how you, in QoD, managed versions and the related existence, or not, of the api-documentation.md file. It is totally clear, thank you. For you it is easy :-) because you have a well implemented release management with branches for EACH sub release. In the Edge Cloud WG we don't have it, for every sub release, of every API in the Family, because we have different APIs with different status. We are anyway working on release management and branches, this will help very much with this documentation issue.

[hdamker]

Consider to carve out the APIs in own repository which are on their way to releases -- will make things much easier 😄 ... as initiated now with SimpleEdgeDiscovery.

Branches won't help you here, as every branch will always contain all files across the repository.

And: the release-0.x.y within QoD are actually not necessary - never really used, the release tags are sufficient to point directly to the released code. Hence the new API Release Process does not have them.