[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:
Blocks
is blocked by FOLIO-1912 Aggregate metadata about RAMLs config... Closed
Relates
relates to FOLIO-1913 Provide cross-references to API docs ... Open
relates to FOLIO-2922 Automate the configuration of API doc... Closed
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" FOLIO-2922 Closed to incorporate that information.

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.

Generated at Thu Feb 08 23:12:27 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.