[FOLIO-2898] Create folio-tools/api-doc, from RAML or OpenAPI source files Created: 03/Dec/20  Updated: 09/Apr/21  Resolved: 15/Mar/21

Status: Closed
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Task Priority: TBD
Reporter: David Crossley Assignee: David Crossley
Resolution: Done Votes: 0
Labels: oas, raml, springway
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Blocks
blocks FOLIO-2922 Automate the configuration of API doc... Closed
Relates
relates to FOLIO-2922 Automate the configuration of API doc... Closed
relates to FOLIO-1253 Improve the generate-api-docs CI job In Progress
relates to FOLIO-3008 Upload build-generated HTML API docs ... Closed
relates to FOLIO-2863 pipeline changes required for Spring ... Blocked
Sprint: DevOps: Sprint 105, DevOps Sprint 109, DevOps Sprint 107, DevOps Sprint 108, DevOps: Sprint 104, DevOps Sprint 106
Development Team: FOLIO DevOps

 Description   

Develop an application to discover and process API description files (RAML or OpenAPI OAS) in a module repository, and generate standalone API documentation.

The generated documentation would be published by CI and integrated to the "API documentation" at https://dev.folio.org/reference/api/

For OAS, use https://github.com/Redocly/redoc

For RAML, use https://github.com/raml2html/raml2html (i.e. as currently used for folio-tools/generate-api-docs)

The application would be able to be run locally, and during CI on merge to main branch. And on finalising a release.



 Comments   
Comment by David Crossley [ 15/Mar/21 ]

This is now done and hooked up to CI via jenkins-pipeline-libs.

Added configuration to Jenkinsfile (see doc) for two repositories.
mod-notes – this has RAML only.
mod-quick-marc – this has both RAML and OAS.

The API documentation that is generated from RAML descriptions is published to the module's same S3 sub-directories as before.

The API documentation that is generated from OAS descriptions is published to the module's S3 sub-directory called "s". See the example for mod-quick-marc/records-editor.

However the "API documentation" at https://dev.folio.org/reference/api/ does not yet provide links to such new OpenAPI-based documentation. That is the task of the next tickets FOLIO-2922 Closed and FOLIO-3018 Closed .

Until those are done, each OpenAPI-based module should provide direct links from their GitHub repository README.

Comment by David Crossley [ 09/Apr/21 ]

https://dev.folio.org/guides/api-doc/

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