semantic-release-openapi

semantic-release-openapi

A Semantic Release plugin to update versions in OpenAPI / Swagger specification files.

Step	Description
verifyConditions	Verify existence of the apiSpecFiles config option, that it resolves to at least one valid .json, .yml, or .yaml file, and that it does not resolve to any other file types.
prepare	Update the info.version field in all matching apiSpecFiles.

Installation

This module is distributed via npm and should be installed as one of your project's devDependencies:

npm install --save-dev semantic-release-openapi

Usage

Configure the plugin wherever you have your semantic-release configuration.

Configuration

This plugin has one configuration option which must be supplied.

Option	Description
apiSpecFiles	An array of OpenAPI / Swagger specification file paths. Glob patterns (e.g. '*.yaml') are supported. All matching files must have a .json, .yaml, or .yml extension.

[!TIP]

Semantic Release will not commit changes to your OpenAPI spec files unless you add the same files in assets for the @semantic-release/git plugin. See the examples below.

Examples

The following examples assume you've put your semantic-release configuration in your package.json file.

Basic Example

{
  "release": {
    "plugins": [
      [
        "semantic-release-openapi",
        {
          "apiSpecFiles": ["openapi.yaml", "src/swagger-*.json"]
        }
      ],
      [
        "@semantic-release/git",
        {
          "assets": ["package.json", "openapi.yaml", "src/swagger-*.json"]
        }
      ]
    ]
  }
}

Extended Example

{
  "release": {
    "branches": ["main"],
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      [
        "@semantic-release/github",
        {
          "assets": [
            {
              "path": "src/openapi.yml",
              "label": "Open API Spec"
            }
          ]
        }
      ],
      "@semantic-release/npm",
      [
        "semantic-release-openapi",
        {
          "apiSpecFiles": ["src/openapi.yml"]
        }
      ],
      [
        "@semantic-release/git",
        {
          "assets": ["package.json", "src/openapi.yml"]
        }
      ]
    ]
  }
}