[FOLIO-2922] Automate the configuration of API documentation Created: 17/Dec/20  Updated: 01/Sep/22  Resolved: 08/Apr/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: devdoc, oas, raml
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Blocks
blocks FOLIO-3018 Utilise the new configuration data to... Closed
is blocked by FOLIO-2898 Create folio-tools/api-doc, from RAML... Closed
Duplicate
duplicates FOLIO-1912 Aggregate metadata about RAMLs config... Closed
Relates
relates to FOLIO-3008 Upload build-generated HTML API docs ... Closed
relates to FOLIO-3028 Temporary display of build-generated ... Closed
relates to FOLIO-903 Add RAML files to api docs configurat... Open
relates to FOLIO-1316 Provide cross-references to API docs ... Closed
relates to FOLIO-2898 Create folio-tools/api-doc, from RAML... Closed
Sprint: DevOps Sprint 111
Development Team: FOLIO DevOps

 Description   

There is currently a manual regular job to maintain configuration for the API docs index at the dev.f.o site. (See notes)

The main reason for this is that the dev.f.o website has no knowledge of the set of API description files (e.g. *.raml) for each of the separate relevant back-end repositories, nor does it know which repositories are relevant. Each of those repositories might add or delete files at any time.

Also in the early days of the project, each of the repositories had a different structure of their RAML areas. Now that is much more consistent, although some do have sub-directories that need to be excluded from processing.

So an automated solution is needed, viz:

When each repository has a merge to its mainline branch, then its API documentation is generated from its API description files (RAML or OpenAPI OAS). Those documents are then published to an AWS S3 bucket, to a sub-directory with the same name as the module.

That "api-doc (doApiDoc)" CI job is assisted by the repository's Jenkinsfile properties (apiTypes and apiDirectories and apiExcludes). It walks the filesystem to find API description files, and compiles a JSON configuration file. The file is deployed to that repository's S3 bucket.

Then an automated regular CI job (perhaps GitHub actions) gathers all of the individual config-doc.json files, aggregates them, and commits the data file to the GitHub repository that controls the dev.f.o website. That commit triggers the rebuild of the site, hence updating the API docs index page.



 Comments   
Comment by David Crossley [ 16/Feb/21 ]

This now also needs to collect the configuration files that are generated by FOLIO-3008 Closed .

Comment by David Crossley [ 08/Apr/21 ]

There is now a GitHub actions workflow "gather-config-apidocs" operating daily to gather configuration pieces and commit datafile changes to "_data/config-apidocs.json"

Next task is FOLIO-3018 Closed .

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