...
- 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 word use of "customer", unless explicitly explained what is meant. Alternative can be Instead use as applicable API consumer, (application) endEnd-user, API consumer, etc or whatever else is applicable.
- avoids reference to CSPs in case use of "Telco/operator/CSP", as also Aggregators, etc. may expose the API. Use e.g. API platform Provider or exposure API platform as applicable.
- avoids the word use of "subscriber". use e.g. "device" instead.Use Device or End-user (defined as the application user) as applicable
- avoids using customer: use API consumer or (application) End-user, as applicable
- 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
...