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

Automate the configuration of API documentation

    XMLWordPrintable

Details

    • DevOps Sprint 111
    • 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.

      TestRail: Results

        Attachments

          Issue Links

            Activity

              People

                dcrossley David Crossley
                dcrossley David Crossley
                Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                  Created:
                  Updated:
                  Resolved:

                  TestRail: Runs

                    TestRail: Cases