build_instructions.md

How to build Open API specs in html, yaml formats

IMPORTANT NOTES:

1. Please do not direclty edit ./release/yaml/*.yaml files directly.
2. Request contributors/reviewers doing pull requests to edit .yaml files in src folders.
3. ./release/yaml/*.yaml files are auto generated using below steps. do

Folder Structure

1. src folder: ./src
2. Published API release folder: ./release
3. Build folder: ./build

Organization of Open API Specficaition

1. All source file are list in folder: ./src/
   Each solution blueprint component holds repsective APIs. e.g.,
   a. registry/registry_core_api_v1.0.0.yaml for registry access
   b. etc.,
2. All open api common components are listed in folder: standards/src/common/ a. schemas
   b. responses
   c. headers
   d. parmeteres
   e. security
   
3. Organisations, Countries and System specific standards are referenced in folder: standards/src/extensions/ a. dci
   b. openId
   c. cdpi
   d. fhir
   

Building Open API consolidated yaml file

1. Make sure all the yaml file have relative path references are resolved and core_xxx_api_vx.x.x.yaml files have reference to all the required files.
2. Install the swagger command line tool using npm (Note: you may need to use root privileges if installing it globally).

sudo npm install -g swagger-cli

3. Generate the resolved OpenAPI definition file
   a. Go to the root directory of this repository i.e standards/
   b. Run the build_apis.cmd from standards/ folder
   b. Alternatively, Run the following command for each index file in ./standards/ folder. for e.g.,
   

swagger-cli -f 2 -t yaml bundle ./src/registry/registry_core_api_v1.0.0.yaml -o ./release/yaml/registry_core_api_v1.0.0.yaml

If the command runs successfully, you should see an output like this for each api index file

Created registry_core_api_v1.0.0.html from release/yaml/registry_core_api_v1.0.0.yaml

4. Install the redocly command line tool using npm (Note: you may need to use root privileges if installing it globally).

sudo npm install -g @redocly/cli

5. To create redoc html pages for easy readability

redocly build-docs ./release/yaml/registry_core_api_v1.0.0.yaml -o ./release/html/registry_core_api_v1.0.0.html

If the command runs successfully, you should see an output like this for each api index file

bundled successfully in: ./release/html/registry_core_api_v1.0.0.html

6. Commit the changes and push the updated code to git repo. Create pull requests for teams to collaborate and merge to main branch!