[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: |
|
||||||||||||||||||||||||||||||||||||||||||||
| 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
|
| 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
|