Skip to content

Files

Latest commit

e0160c7 · Jun 26, 2024

History

History
This branch is 65 commits behind Consensys/teku:master.

.openapidoc

Teku OpenAPI Spec Publish

This directory contains NodeJS project which publishes Teku OpenAPI specifications to gh-pages branch via CI job after tests are green. See publishOpenApiSpec job in .circleci/config.yml.

The actual up-to-date generated doc is available at https://consensys.github.io/teku/

Procedure

The script performs following tasks:

  • Extract spec from Teku latest docker image by reaching the spec endpoint
  • Create dist directory (this folder will be pushed to gh-pages branch)
  • Copy the specs to dist as teku-latest.json (and latest.json for retro-compatibility on the name).
  • Update the spec version file depending on tag existence for the build

For release version (when tagged with CalVer version), it performs following additional steps:

  • Copy the spec to dist as teku-<version>.json
  • Fetch https://github.com/Consensys/teku/raw/gh-pages/versions.json
  • Update versions' json with release versions by updating stable.spec and stable.source to the release version and adding a new entry for it. For example after adding spec version 20.11.0, the versions.json would look like:
{
 "latest": {
  "spec": "latest",
  "source": "master"
 },
 "stable": {
  "spec": "20.11.1",
  "source": "20.11.1"
 },
 "20.11.0": {
  "spec": "20.11.0",
  "source": "20.11.0"
 }
 "20.11.1": {
  "spec": "20.11.1",
  "source": "20.11.1"
 }
}
  • Save updated versions.json to dist folder.
  • Push the dist folder to gh-pages branch. The script is using gh-pages npm module to automate this step.

Environment variables

Following environment variables can be used to override defaults

  • OA_GIT_URL (default: git@github.com:Consensys/teku.git)
  • OA_GH_PAGES_BRANCH (default: gh-pages)
  • OA_GIT_USERNAME (default: CircleCI Build)
  • OA_GIT_EMAIL (default: ci-build@consensys.net)

Following should only be overridden if changing the project

  • OA_VERSIONS_FILE_NAME (default: versions.json)
  • OA_DIST_DIR (default: ./dist)
  • OA_SPEC_URL (default: http://localhost:5051/swagger-docs)
  • OA_SPEC_DIR (default: ./openapidoc/spec)