Uploaded image for project: 'FOLIO'
  1. FOLIO
  2. FOLIO-2922

Automate the configuration of API documentation



    • DevOps Sprint 111
    • FOLIO DevOps


      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.

      TestRail: Results


          Issue Links



                dcrossley David Crossley
                dcrossley David Crossley
                0 Vote for this issue
                1 Start watching this issue



                  TestRail: Runs

                    TestRail: Cases