[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: |
|
||||||||||||||||||||||||||||
| Issue links: |
|
||||||||||||||||||||||||||||
| 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
|
| 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/ 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. 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: |
| Comment by David Crossley [ 17/Feb/21 ] |
|
Part 2 to display in the API Docs tables will be done later. See tickets
|