specs

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

  4. src folder: ./src
  5. Published API release folder: ./release
  6. 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
  1. 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
  1. 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
  1. 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
  1. Commit the changes and push the updated code to git repo. Create pull requests for teams to collaborate and merge to main branch!
This site is open source. Improve this page.