[FOLIO-3008] Upload build-generated HTML API docs to S3 Created: 10/Feb/21  Updated: 19/Feb/21  Resolved: 16/Feb/21

Status: Closed
Project: FOLIO
Components: Continuous Integration, Documentation
Affects versions: None
Fix versions: None

Type: Task Priority: P2
Reporter: Bohdan Suprun (Inactive) Assignee: David Crossley
Resolution: Done Votes: 0
Labels: devdoc, oas, raml
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Attachments: HTML File index.html    
Issue links:
Blocks
blocks MSEARCH-51 Generate static OpenAPI doc page Closed
Relates
relates to FOLIO-2898 Create folio-tools/api-doc, from RAML... Closed
relates to FOLIO-3018 Utilise the new configuration data to... Closed
relates to FOLIO-3028 Temporary display of build-generated ... Closed
relates to FOLIO-2922 Automate the configuration of API doc... Closed
Sprint: DevOps Sprint 108
Development Team: FOLIO DevOps

 Description   

For mod-search we're using OpenAPI 3.0 as API specification (vs RAML as most of the modules) and we want to upload our API documentation to https://dev.folio.org/reference/api/.

We're able to generate the API doc during build time, the CI process should pick the page (for now it is target/docs/index.html) and upload it to S3.

Sample generated page index.html



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

There are various tasks to achieve this.

1) Prepare the list of files, and upload to S3

This should be relatively easy, and we will get this done first. So at least the docs get published promptly.

2) Display the module and its files at dev.f.o site

This is the more difficult part – making the dev.f.o site aware that there is a module with api docs to be added to the table. The website must only do minimal build processing. So need a separate process to regularly gather the various lists of files, assemble a data file, and commit it to git at the website's _data directory.

Leaving Part 2 to separate tickets FOLIO-2922 Closed and FOLIO-3018 Closed .

Comment by David Crossley [ 12/Feb/21 ]

So these are the components needed to enable part 1.

Considering all potential OpenAPI-based modules, not just mod-search. Also the solution could be relevant for RAML-based modules too. So not limiting.

The directory name for the build-generated files will be target/apidocs/
In the future, modules might generate other "docs", so use a specific name "apidocs". All files in that directory will be uploaded as API documentation.

Modules could have multiple documentation files, generated from the separate API description files. For example, mod-password-validator currently has two (password-validator.yaml and validator-registry.yaml).

The filenames of the build-generated documentation will match the source filenames of their input "API description" files. So not "index.html" but instead corresponding "password-validator.html" and "validator-registry.html" names.
Note how column 1 of the table at https://dev.folio.org/reference/api/#mod-password-validator uses the name of each source "API description" file, and directly links to its git source.

The module's Jenkinsfile will have a property doUploadApidocs. When "true" then FOLIO CI will inspect its build output "apidocs" directory, and assemble a data file listing of all documentation files. Then proceed to upload that listing and the files to the module's S3 space.

Comment by David Crossley [ 15/Feb/21 ]

The Part 1 is done now.

The upload happens on merge to mainline branch and on release.

Comment by David Crossley [ 16/Feb/21 ]

Verified via the merge of https://github.com/folio-org/mod-search/pull/22

Deployed to:
https://s3.amazonaws.com/foliodocs/api/mod-search/u/files-upload.txt
https://s3.amazonaws.com/foliodocs/api/mod-search/u/mod-search.html

Comment by David Crossley [ 17/Feb/21 ]

Part 2 to display in the API Docs tables will be done later. See tickets FOLIO-2922 Closed and FOLIO-3018 Closed .

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