...
- Check Info object
- version: aligned with the released API version and formatted correctly (per Commonalities)
- description:
- contains sufficient in-line API documentation
- does not use Telco Jargon / abbreviations (non blocking for release if in documentation)
- contains the section on auth from ICM 0.2.0 CAMARA-API-access-and-user-consent.md (with no link to ISM release in it - apply for next meta-release to API specs Herbert Damker to check with ICM team.
- avoids the use of the word "customer", unless explicitly explained what is meant. Alternative can be (application) end-user, API consumer, etc.
- avoids reference to CSPs in case also Aggregators, etc. may expose the API. Use e.g. API platform or exposure platform.
- avoids the word "subscriber". use e.g. "device" instead.
- presence of the x-camara-commonalities release referenced, e.g. 0.4.0-rc.1 or 0.4.0.
- Check servers object has the correct version format e.g. v0.xrc1, v1rc1, v0.x or v1.
- Check security schemes: check presence and format (OIDC) and scope name format.
- Is there a way to know if an API requires consent request ? No, this is local regulation. It is covered when using the security scheme and the scope rules.
- In externalDocs: this field is optional, but recommend to point to the CAMARA, repo.
description: Project documentation at CAMARA
url: https://github.com/camaraproject/<repo>- Tanja de Groot to create a Commonalities backlog issue
- Shall error cases be explained in in-line documentation ? (info.description) It seems yes as per Commonalities/documentation/API-DocumentationTemplate.md - Deprecate the doc and doc shall be inline in OAS spec. @Rafal to updater in Commonalities
...