[FOLIO-1316] Provide cross-references to API docs via endpoint Created: 28/Jun/18 Updated: 12/Sep/22 Resolved: 12/Sep/22 |
|
| Status: | Closed |
| Project: | FOLIO |
| Components: | None |
| Affects versions: | None |
| Fix versions: | None |
| Type: | New Feature | Priority: | P3 |
| Reporter: | David Crossley | Assignee: | David Crossley |
| Resolution: | Done | Votes: | 0 |
| Labels: | devweb, raml | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original estimate: | Not Specified | ||
| Issue links: |
|
||||||||||||||||||||
| Sprint: | DevOps Sprint 146 | ||||||||||||||||||||
| Development Team: | FOLIO DevOps | ||||||||||||||||||||
| Description |
|
The API docs dev.folio.org/reference/api/ are generated from the RAML and OpenAPI (OAS) description files in each back-end module. This is done via the CI job api-doc. There could also be cross-references to those docs. That would assist a developer who knows a path URI, to find the responsible module and link directly to the particular API docs. Update: 2022-09-12 Done. https://dev.folio.org/reference/api/endpoints/ (See explanation in Jira comment.) |
| Comments |
| Comment by David Crossley [ 28/Jun/18 ] |
|
While the job is analysing a repository's API description files, it could gather the top-level endpoints from each. (It could gather info from its ModuleDescriptor, but that would not enable linking directly to the explicit relevant API description file and its generated docs.) The build system for presenting the API docs at dev.f.o could retrieve that data file and generate a cross-reference table. Note that it would be better to generate a well-structured data file, to reduce the amount of processing needed at the website end. |
| Comment by David Crossley [ 01/Sep/22 ] |
|
I now have a local solution to utilise the "amf-client-js" dependency that is used by our new "api-lint" tool. Its internal model knows all of the declared endpoints for each processed API description. Enhance our "api-doc" CI tool to gather those while it is building that module's API documentation during the merge to mainline stage, and also deploy that summary configuration to AWS S3 when it deploys the generated API docs. Enhance the GitHub workflow "gather-config-apidocs"
Develop a new page at dev.f.o (with Jekyll Liquid) to present all endpoints and link each directly to the relevant API documentation.
|
| Comment by David Crossley [ 12/Sep/22 ] |
|
Done. See: https://dev.folio.org/reference/api/endpoints/ Summary: For each relevant back-end module, during its merge to mainline phase of CI, the api-doc facility enhances its config-doc.json file. Deploys to AWS S3 as normal. The api-doc facility is now also using AMF which builds an internal model including the set of API endpoints. The daily GitHub workflow "gather-config-apidocs" obtains each data file from S3 and builds a data file `_data/config-api-endpoints.json` as a list of endpoints, each with additional properties to facilitate linking. (That data file could potentially also be used by other facilities.) The Liquid code behind the `reference/api/endpoints.md` utilises that data file to build the table with links directly to each relevant section of that module's API documentation, as explained. |