https://github.com/aensley/semantic-release-openapi
A Semantic Release plugin to update versions in OpenAPI / Swagger specification files
https://github.com/aensley/semantic-release-openapi
oas oas-spec oas2 oas3 oas31 openapi openapi-spec openapi-specification openapi3 semantic-release semantic-release-plugin swagger swagger-api
Last synced: 16 days ago
JSON representation
A Semantic Release plugin to update versions in OpenAPI / Swagger specification files
- Host: GitHub
- URL: https://github.com/aensley/semantic-release-openapi
- Owner: aensley
- License: mit
- Created: 2022-10-02T19:15:09.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2026-06-23T15:58:52.000Z (about 1 month ago)
- Last Synced: 2026-06-23T17:24:51.355Z (about 1 month ago)
- Topics: oas, oas-spec, oas2, oas3, oas31, openapi, openapi-spec, openapi-specification, openapi3, semantic-release, semantic-release-plugin, swagger, swagger-api
- Language: TypeScript
- Homepage: https://npmjs.com/package/semantic-release-openapi
- Size: 489 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# semantic-release-openapi
[][npm]
[][npm]
[](https://github.com/aensley/semantic-release-openapi/blob/main/LICENSE)
[](https://prettier.io)
[][npm]
[](https://libraries.io/npm/semantic-release-openapi)
[][qltysh]
[][qltysh]
[](https://github.com/aensley/semantic-release-openapi/actions/workflows/test.yml)
[](https://scorecard.dev/viewer/?uri=github.com/aensley/semantic-release-openapi)
[](https://socket.dev/npm/package/semantic-release-openapi)
[](https://security.snyk.io/package/npm/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`:
```bash
npm install --save-dev semantic-release-openapi
```
## Usage
Configure the plugin wherever you have your [semantic-release configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#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](https://www.gnu.org/software/bash/manual/bash.html#Pattern-Matching) (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
```json
{
"release": {
"plugins": [
[
"semantic-release-openapi",
{
"apiSpecFiles": ["openapi.yaml", "src/swagger-*.json"]
}
],
[
"@semantic-release/git",
{
"assets": ["package.json", "openapi.yaml", "src/swagger-*.json"]
}
]
]
}
}
```
### Extended Example
```json
{
"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"]
}
]
]
}
}
```
[npm]: https://www.npmjs.com/package/semantic-release-openapi
[qltysh]: https://qlty.sh/gh/aensley/projects/semantic-release-openapi