# @team-supercharge/oasg

> Node-based tool to lint OpenAPI documents and generate clients, servers and documentation from them

Latest version **20.1.0** (published 2026-11-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install @team-supercharge/oasg
pnpm add @team-supercharge/oasg
yarn add @team-supercharge/oasg
bun add @team-supercharge/oasg
```

Provides the command `oasg`.

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 20.1.0 |
| Published | 2026-11-06 |
| First published | 2021-08-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=24.21 |
| Dependencies | 17 |
| Unpacked size | 710.2 KB |
| Known vulnerabilities | 0 (+2 in 2 direct dependencies) |
| Install scripts | no |
| Author | Supercharge |
| Maintainers | rashan86, sc-gitlab-ci, martontoth-sc, exoszajzbuk, martontoth-deploy, csutorasr, kisfejes, sc-levi, nagy.gao |

## Links

- npm: https://www.npmjs.com/package/@team-supercharge/oasg
- Repository: https://gitlab.com/team-supercharge/oasg
- Homepage: https://gitlab.com/team-supercharge/oasg#readme
- Issues: https://gitlab.com/team-supercharge/oasg/issues
- npm.io page: https://npm.io/package/@team-supercharge/oasg

## Dependencies (17)

- [ajv](https://npm.io/package/ajv.md) ^8.17.1
- [glob](https://npm.io/package/glob.md) ^10.2.1
- [yargs](https://npm.io/package/yargs.md) ^17.7.1
- [yamljs](https://npm.io/package/yamljs.md) ^0.3.0
- [express](https://npm.io/package/express.md) ^4.18.2
- [js-yaml](https://npm.io/package/js-yaml.md) ^4.3.0
- [@redocly/cli](https://npm.io/package/@redocly/cli.md) 1.34.5
- [command-exists](https://npm.io/package/command-exists.md) ^1.2.9
- [express-http-proxy](https://npm.io/package/express-http-proxy.md) ^1.6.3
- [swagger-ui-express](https://npm.io/package/swagger-ui-express.md) ^5.0.1
- [@stoplight/prism-cli](https://npm.io/package/@stoplight/prism-cli.md) 5.12.0
- [openapi-to-postmanv2](https://npm.io/package/openapi-to-postmanv2.md) 6.3.0
- [@stoplight/spectral-cli](https://npm.io/package/@stoplight/spectral-cli.md) 6.14.1
- [json-schema-merge-allof](https://npm.io/package/json-schema-merge-allof.md) ^0.8.1
- [@apidevtools/swagger-parser](https://npm.io/package/@apidevtools/swagger-parser.md) ^10.1.0
- [@apidevtools/json-schema-ref-parser](https://npm.io/package/@apidevtools/json-schema-ref-parser.md) ^10.1.0
- [openapi-typescript-validator-ext-ref](https://npm.io/package/openapi-typescript-validator-ext-ref.md) ^3.2.0-external-ref-support

## Recent versions

- 20.1.0 (latest) — 2026-11-06
- 20.1.0-temp-feat-apple-swift-openapi-generator-1-14-4.d78c2b2c (next) — 2026-11-10
- 20.0.0-temp-feat-spring-kotlin-declared-errors.f5688282 — 2026-11-03
- 20.0.0-temp-t3-nestjs-upstream-flow.490abb2b — 2026-10-22
- 20.0.0-temp-t3-nestjs-upstream-flow.8440153c — 2026-10-22
- 20.0.0-temp-t3-nestjs-upstream-flow.236dad67 — 2026-10-22
- 20.0.0-temp-t3-nestjs-upstream-flow.2e4b1cf6 — 2026-10-22
- 20.0.0 — 2026-09-14
- 19.0.1 — 2026-09-09
- 19.0.0 — 2026-08-28
- 18.3.4 — 2026-08-28
- 18.3.3 — 2026-08-07
- 18.3.2-temp-feat-jvm-breaking.dc62c9df — 2026-07-31
- 18.3.2 — 2026-07-31
- 18.3.1-temp-feat-jvm-breaking.c418dc3b — 2026-07-29
- … 278 more at https://npm.io/package/@team-supercharge/oasg/versions

## README

# **OAS**g - **Open Api Spec** generator

Design APIs in OpenAPI 3.0 format, lint them, and generate client/server packages.

* [Getting Started](#getting-started)
	* [Required Tools](#required-tools)
	* [Initialize API Repo](#initialize-api-repo)
  * [Create `.config.json`](#create-config.json)
  * [Configure Linter](#configure-linter)
  * [Use with Docker](#use-with-docker)
  * [Use with GitLab CI](#use-with-gitlab-ci)
* [Version Overview](#version-overview)
* [Usage](#usage)
* [Linter Rules](#linter-rules)
  * [Custom Rules](#custom-rules)
  * [Custom Functions](#custom-functions)
* [Template Customization](#template-customization)
* [Configuration](#configuration)
  * [Source](#source)
    * [Source Types](#source-types)
    * [Overrides](#overrides)
  * [Target](#target)
    * [Target Types](#target-types)
* [Migration Guide](#migration-guide)
* [Roadmap](#roadmap)

---

# Getting Started

## Required tools

For using the tool you need `wget`, `jq` and `java` pre-installed. The required dependencies and __OASg__ itself is preinstalled in a Docker image distributed in the `registry.gitlab.com/team-supercharge/oasg` registry with every new release of the project.

## Initialize API repo

Create a new repository for your API service, and add a `package.json` like the following example and run `npm install`.

```json
{
    "name": "@example/api",
    "private": true,
    "version": "0.0.0",
    "description": "API client generator service for Example",
    "scripts": {},
    "repository": {
      "type": "git",
      "url": "git@gitlab.supercharge.io:misc/oasg-example.git"
    },
    "dependencies": {
      "@team-supercharge/oasg": <insert-latest-version>
    }
  }
```

## Create `config.json`

In your API service repository, create a `config.json` file, for which the structure needs to be the following:

```json
{
  "sources": [
    { source-item }
  ],
  "targets": [
    { target-item }
  ],
}
```

For detailed configuration instructions please refer to the [Configuration](#configuration) section below.

## Configure Linter

Create a `.spectral.js` file in the repo's root directory with the following minimal content:

```js
import oasgRuleset from '@team-supercharge/oasg/ruleset';

export default {
  extends: oasgRuleset
};
```

The file is used for configuring [Spectral](https://stoplight.io/open-source/spectral/) on a per-project basis and will enable usage of the base _OASg_ ruleset and enables to add project-specific rules as well. For detailed instructions on how to use custom rules refer to the [Linter rules](#linter-rules) section below.

> ⚠️ The YAML ruleset format is highly discouraged to be used, as it won't work seamlessly [when being used with Docker](#use-with-docker).

## Use with Docker

Each release of _OASg_ is also distributed as a Docker image with the respective version of the NPM package preinstalled. You can use the `registry.gitlab.com/team-supercharge/oasg` image and simply run the `oasg` command in the running container.

Full example with **GitLab CI**:

```yaml
swaggerlint:
  image: registry.gitlab.com/team-supercharge/oasg:<version>
  stage: check
  script:
    - oasg lint
```

> If no other dependency is needed for the API project being built, there is no need to run any `npm install` or `npm ci` commands before invoking `oasg`

## Use with GitLab CI

Built on the [Docker](#use-with-docker) setup, a set of predefined templates are readily available for GitLab CI.

When your project is hosted on gitlab.com __OASg__ should always be included in your projects `.gitlab-ci.yml` by explicitly specifying a version, like this:

```yaml
include:
  - project: team-supercharge/oasg
    file: gitlab-ci-templates.yml
    ref: <version tag>
```

when your project is hosted on a self-managed GitLab instance use the following snippet:

```yaml
include:
  - remote: https://gitlab.com/team-supercharge/oasg/raw/<version-tag>/gitlab-ci-templates.yml
```

---

# Version Overview

The table below gives an overview of the changes (breaking, non-breaking, bug fixes) introduced in various major versions. For the resolution of breaking changes please consult the [Migration Guide](#migration-guide).

| Component                        |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
|----------------------------------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| **Internal**                     | 19 | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
| _Core_                           |➖  |✨  |💥  |✨  |🐛  |💥  |✨  |🐛  |✨  |➖  |✨  |🐛  |🐛  |➖  |💥  |💥  |✨  |💥  |🆕  |
| _Linter_                         |➖  |➖  |➖  |🐛  |➖  |➖  |➖  |➖  |💥  |➖  |➖  |➖  |➖  |🐛  |➖  |✨  |💥  |🆕  |
| **Client Targets**               | 19 | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
| `android`                        |➖  |✨  |➖  |➖  |➖  |🐛  |💥  |➖  |➖  |💥  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
| `angular`                        |➖  |➖  |➖  |✨  |➖  |🐛  |💥  |➖  |➖  |➖  |🐛  |➖  |➖  |➖  |💥  |➖  |➖  |➖  |🆕  |
| `dotnet`                         |➖  |✨  |➖  |➖  |➖  |🆕  |
| `dotnet-system-text-json`        |➖  |🆕➖|
| `dotnet-webapi`                  |➖  |✨  |➖  |🆕➖|
| `dotnet-webapi-system-text-json` |➖  |🆕➖|
| `feign`                          |💥  |🐛  |🐛  |✨  |➖  |➖  |➖  |➖  |➖  |✨  |💥  |💥  |➖  |➖  |🐛  |🐛  |🆕  |
| `feign-kotlin`                   |💥  |🐛  |🐛  |✨  |➖  |➖  |➖  |➖  |➖  |🆕  |
| `plain-java`                     |➖  |🐛  |🐛  |🆕  |
| `flutter`                        |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
| `ios`                            |➖  |➖  |➖  |➖  |➖  |➖  |💥  |🐛  |➖  |➖  |➖  |✨  |➖  |💥  |➖  |➖  |✨  |🆕  |
| `apple-swift`                    |➖  |➖  |➖  |🆕  |
| `kmp`                            |➖  |✨  |✨  |➖  |➖  |🆕  |
| `python`                         |➖  |🐛  |➖  |🆕  |
| `python-legacy`                  |➖  |🐛  |➖  |💥  |➖  |🐛  |💥  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
| `react`                          |➖  |💥  |➖  |🐛  |🐛  |➖  |💥  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
| `typescript-axios`               |➖  |✨  |➖  |🆕  |
| `typescript-fetch`               |➖  |✨  |➖  |🆕  |
| **Server Targets**               | 19 | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
| `nestjs`                         |➖  |✨  |🐛  |💥  |💥  |➖  |💥  |✨  |➖  |➖  |🐛  |➖  |➖  |✨  |🆕  |
| `python-fastapi`                 |➖  |➖  |➖  |➖  |➖  |🆕  |
| `python-fastapi-raw-request`     |➖  |➖  |➖  |➖  |➖  |🆕  |
| `spring`                         |💥  |🐛  |🐛  |✨  |➖  |➖  |➖  |➖  |➖  |✨  |💥  |💥  |➖  |➖  |➖  |✨  |➖  |🆕  |
| `spring-kotlin`                  |💥  |🐛  |✨  |✨  |➖  |➖  |➖  |➖  |➖  |✨  |💥  |💥  |➖  |➖  |🐛  |✨  |➖  |🆕  |
| **Misc Targets**                 | 19 | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
| `contract-testing`               |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
| `openapi`                        |➖  |➖  |➖  |➖  |➖  |➖  |➖  |💥  |➖  |➖  |✨  |➖  |🆕  |
| `stubby`                         |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |💥  |➖  |➖  |➖  |➖  |🆕  |
| `postman`                        |➖  |➖  |➖  |➖  |🆕  |
| `msw`                            |➖  |🆕  |

**Legend:**

* 🆕 feature/target introduced
* 💥 breaking changes
* ✨ new features added
* 🐛 bug fixes only

---

# Usage

## `lint`

Lints the API specification file of the specified target using [Spectral](https://stoplight.io/open-source/spectral). If no target specified, all targets will be linted.

```shell
$ npx oasg lint [source]
```

## `serve`

Bundles the specified source and serves with [Swagger UI](https://swagger.io/tools/swagger-ui/), hooked up internally with a local proxy server to circumvent CORS limitations.

```shell
$ npx oasg serve [source]
```

## `proxy`

Fires up a [Prism](https://stoplight.io/open-source/prism) validation proxy server which can be used to interactively debug and validate that a remote server's responses are in line with the defined source specification.

```shell
$ npx oasg proxy [source] --server
```

or

```shell
$ npx oasg proxy [source] -s
```

## `generate`

Generates the API client package of the specified target. If no target specified, all targets will be generated.

```shell
$ npx oasg generate [target]
```

## `publish`

Publishes the generated API client package of the specified target. If no target specified, all targets will be published.

```shell
$ npx oasg publish [target]
```

## `save-lock`

Saves the current state of the package-lock.json file to the `.oasg` directory. This is useful for later restoring the lock file in case of a failed install or build.
This command is offered for `npm` based projects only to ensure that a working `package-lock.json` file is always available for the project.

```shell
$ npx oasg save-lock [target]
```

## Dependency install cooldown

`npm install` only resolves package versions that have been on the registry for at least 7 days, so a
compromised release has a week to be caught and unpublished before it can reach a build. This is the
`NPM_CONFIG_MIN_RELEASE_AGE` npm setting, and it applies in two places:

* the _OASg_ image sets it for its own dependencies and CLI installs
* the target scripts set it for the installs the `npm` based targets (`angular`, `nestjs`, `msw`,
  `react`, `contract-testing`, `typescript-axios`, `typescript-fetch`) perform while building the
  generated SDK, so the cooldown holds even when _OASg_ runs outside its own image

`npm ci` is unaffected by design: it installs exactly what the lock file pins, which is what
[`save-lock`](#save-lock) is for.

If a target has to pick up a fresher release (a framework version published within the cooldown, for
example), override the variable on the job:

```yaml
generate-sdk:
  extends: .oasg
  variables:
    NPM_CONFIG_MIN_RELEASE_AGE: "0"
```

---

# Linter Rules

_OASg_ makes use of the awesome [Spectral](https://stoplight.io/open-source/spectral/) project to provide linting capabilities and comes with a set of more strict default rules we call the _OASg Ruleset_ which is defined in the file [ruleset/ruleset.js](ruleset/ruleset.js) and exported as `@team-supercharge/oasg/ruleset` for the outside world.

The project's `.spectral.js` file in the API repository should be always configured to extend the default _OASg Ruleset_ using the methods described in the [Configure linter](#configure-linter) section.

Rules defined in the ruleset can be split into two categories:

  * **default rules** - rules that are enabled by default, can be disabled with the `rule-name: off` syntax
  * **opt-in rules** - rules that need to be explicitly enabled with the `rule-name: true` syntax

You can further customize the ruleset in `.spectral.js` according to the [documentation](https://meta.stoplight.io/docs/spectral/docs/guides/4-custom-rulesets.md) using the `rules:` property.

An example configuration can be found here:

```js
import oasgRuleset from '@team-supercharge/oasg/ruleset';

import { truthy } from '@stoplight/spectral-functions';

export default {
  extends: oasgRuleset,
  rules: {
    'oasg-object-names-pascal-case': false,          // disables a default rule - don't do this in general :)
    'oasg-object-names-api-model-suffix': true,      // enables a non-default rule

    'oasg-path-casing-kebab': false,                 // switches a default rule to another one
    'oasg-path-casing-pascal': true,

    'my-rule-name': {                                // adds a fully custom rule which applies to only your project
      description: 'Tags must have a description.',
      given: '$.tags[*]',
      severity: 'error',
      then: {
        field: 'description',
        function: truthy
      }
    }
```


```yaml
extends: '@team-supercharge/oasg/ruleset'

rules:
  oasg-object-names-pascal-case: off             # disables a default rule - don't do this in general :)
  oasg-object-names-api-model-suffix: true       # enables a non-default rule

  oasg-path-casing-kebab: off                    # switches a default rule to another one
  oasg-path-casing-pascal: true

  my-rule-name:                                  # adds a fully custom rule which applies to only your project
    description: Tags must have a description.
    given: $.tags[*]
    severity: error
    then:
      field: description
      function: truthy
```

## Custom Rules

The following rules are defined in the custom _OASg Ruleset_.

> ⚠️ From the rules in the same group only one can be enabled at a time as they are colliding with each other. Please turn off the default one and enable the other if you intend to change the default behaviour.

| Group | Rule | Default | Description |
|-|-|-|-|
| | `oasg-object-names-pascal-case` | Y | Every object defined in the spec (schemas, requests, responses) should be `PascalCased`, as they are most likely to be converted into classes / enums / objects during code generation |
| | `oasg-object-names-api-model-suffix` | | makes sure every schema, request, response has the `ApiModel` suffix (used to avoid naming collision) |
| | `oasg-operation-ids-camel-case` | Y | The `operationId` properties for paths should be `camelCased`, as they are converted to class methods during code generation |
| path casing | `oasg-path-casing-kebab`  | Y | enforces `kebab-casing` for path segments |
| path casing | `oasg-path-casing-snake`  |   | enforces `snake_casing` for path segments |
| path casing | `oasg-path-casing-camel`  |   | enforces `camelCasing` for path segments |
| path casing | `oasg-path-casing-pascal` |   | enforces `PascalCasing` for path segments |
| property casing | `oasg-property-casing-kebab`  |   | enforces `kebab-casing` for property names |
| property casing | `oasg-property-casing-snake`  |   | enforces `snake_casing` for property names |
| property casing | `oasg-property-casing-camel`  | Y | enforces `camelCasing` for property names |
| property casing | `oasg-property-casing-pascal` |   | enforces `PascalCasing` for property names |

## Custom Functions

Custom functions in project configuration can be only used with using the [JavaScript Ruleset Format](https://docs.stoplight.io/docs/spectral/aa15cdee143a1-java-script-ruleset-format) supported by Spectral. The functions can be imported from `@team-supercharge/oasg/functions`.

### `schemaEnumeration`

The function enables to verify a value against a set of enumeration values defined in a schema.

Function parameters:
* `schema` - Name of the schema to be validated against, must contain `enum` definition
* `file` - (optional) YAML file with `components.schemas` defined, otherwise the currently linted document is used

Example usage in a custom project ruleset:

```js

import oasgRuleset from '@team-supercharge/oasg/ruleset';

import { schemaEnumeration } from '@team-supercharge/oasg/functions'

export default {
  extends: oasgRuleset,
  rules: {
    'empire-valid-permissions': {
      recommended: true,
      type: 'style',
      severity: 'error',
      message: '{{error}}',
      description: 'Property x-permissions should use values from the Permission enum',
      given: '$.paths.*.*.x-permissions[*]',
      then: {
        function: schemaEnumeration,
        functionOptions: {
          file: './api/common.yaml',
          schema: 'Permission'
        }
      }
    },
  }
};
```

---

# Template Customization

Using the coming `templateDir` config parameter there is a possibility to customize the templates used during generation.

OASg offers two levels of customization:

The **"OASg level"** customizations can be placed for every target in OASg's source code itself in the `targets/{targetId}/templates` directory. This level can be useful for:
  * adding common functionality which are to be used across every project using OASg
  * fixing bugs/problems in output of the specific version of OpenAPI Generator

The **"project level"** customization can be configured using the `templateDir` parameter for any [Target](#target)
  * if you specify a directory there, the contents of it will be __copied over__ the templates from the previous level

> ⚠️ At any level if you want to introduce a customized template, always make sure you start from the **right version**:
> 1. for **OASG level** customizations always check the version field in `DEFAULT_GENERATOR_MAPPING` for your selected [Target](#target) and copy the [original template](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources) from the right tag!
> 2. for **project level** customizations check first if the selected template is already customized on **OASG level**, in that case copy the template from the OASg source code

---

# Configuration

## Source

The _OASg_ tool distinguish 2 kinds of source types.

Common source parameters

|Parameter| Description| Required | Default |
|-|-|-|-|
| id | Unique identifier | Y | - |
| type | Source type: `simple` / `merged` | N | `simple` |
| bundle | Bundle specification into a single file | N | `true` |
| sortSchemas | Sort `components.schemas` alphabetically | N | `true` |
| decorators | Array of files for decorator functions | N | `[]` |
| cleanup | Cleans specification from unused paths, tags and schemas | N | `true` |
| overrides | Override properties of the OpenApi file | N | - |

The source specification is by default bundled into a single file (resolving external dependencies) using the [@redocly/cli package's](https://www.npmjs.com/package/@redocly/cli) `bundle` command.

> ⚠️ It is highly recommended to keep `bundle` on if you plan to use the `openapi` target type, as external refs won't be part of the target artifact.

Decorator files must export a `decorate(document)` function which transforms the parsed OpenAPI document and returns it at the end of the function.

Full example with decorators:

```json
{
  "id": "platform-api",
  "type": "merged",
  "inputs": [
    "api/*.openapi.yaml"
  ],
  "bundle": false,
  "sortSchemas": false,
  "decorators": ["decorators/one", "decorators/two"],
  "cleanup": false
}
```

```js
// decorators/one.js

function decorate(document) {
  document.info.title = 'My Custom Decorated Title';

  return document;
}

exports.decorate = decorate;
```

After the decorators have run, the specification is by default cleaned up (can be turned off by setting the `"cleanup": false` option):
  - `paths` with no methods in them are removed
  - `tags` with no endpoints using them are removed
  - `components` that are unused are removed (only if `bundle` option is also enabled)

### Source Types

#### Simple

A single file can be used as an input.

```json
{
  "id": "source-simple",
  "type": "simple",
  "input": "api/swagger1.yaml",
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| input | Path of the OpenApi specification file | N | `api/openapi.yaml` |

#### Merged

More files are merged into a single OpenApi specification file and used as an input. The files are merged in the order they are defined in the `inputs` array. Take care during naming of the schemas, as they are merged into a single namespace.

Glob patterns are supported.

```json
{
  "id": "source-merged",
  "type": "merged",
  "inputs": [
    "api/swagger1.yaml",
    "api/swagger/*.yaml"
  ]
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| inputs | Array of paths of specification files or globs | Y | - |

### Overrides

The following sections can be overridden: `info`, `externalDocs`, `license` and `contact`.

It does not override but replace the values of the OpenApi Specification with the corresponding values of the `config.json`.

You can check [here](https://gitlab.supercharge.io/misc/oasg/-/blob/master/config.schema.yml) which values are required.

```json
"overrides": {
  "info": {
    "title": "Overridden Frontend API",
    "description": "Overridden Frontend Merged API Description",
    "termsOfService": "Overridden Terms Of Service",
    "version": "1.0.2"
  },
  "externalDocs": {
    "description": "Overridden externalDocs",
    "url": "https://supercharge.io"
  },
  "license": {
    "name": "Overridden License"
  },
  "contact": {
    "name": "Overridden Contact",
    "url": "https://supercharge.io",
    "email": "hello@supercharge.io"
  }
}
```

## Target

Common target parameters

|Parameter| Description| Required | Default |
|-|-|-|-|
| id | Unique identifier | Y | - |
| type | Platform identifier | Y | - |
| generatorId | Code generator identifier: it defines the specific type of generator | N | default |
| source | Identifier of the source object | N | default |
| generator | OpenApi Generator: it can be a released version or a http(s) URL | N | 4.3.1 |
| templateDir | Path for customized OpenAPI Generator templates | N | - |

### Target Types

#### `angular`

```json
{
  "id": "client-angular",
  "type": "angular",
  "source": "source-simple",
  "packageName": "@project/oasg-example-angular",
  "repository": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/npm/"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Name of the generated NPM package | Y | - |
| repository | URL of the NPM package registry | Y | - |

#### `react`

```json
{
  "id": "client-react",
  "type": "react",
  "source": "source-merged",
  "packageName": "@project/oasg-example-react-native",
  "repository": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/npm/"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Name of the generated NPM package | Y | - |
| repository | URL of the NPM package registry | Y | - |

**Usage**<br>

1. Provide API config and instances

Let's create a component to setup API configuration and the APIs you need. Wrap your application with this components afterwards.

```tsx
import { type Type, type APIS, type ConfigurationParameters, ApiConfigProvider, ApiInstancesProvider, UsersApi } from '@project/oasg-example-react';

// Provide here all the APIs you need (might change during the project)
const providedApis: Type<APIS>[] = [UsersApi];

const ApiProvider = ({ children }) => {
  const config = useMemo<ConfigurationParameters>(
    () => ({
      basePath: 'https://your-api-url.domain',
      middlewares: [/* Your middlewares, eg. adding authorization header */]
    }),
    []
  );

  return (
    <ApiConfigProvider config={config}>
      <ApiInstancesProvider apis={providedApis}>{children}</ApiInstancesProvider>
    </ApiConfigProvider>
  );
};
```

2. Using the hooks

The SDK exposes two React hooks for each endpoints: a query and a mutation. Their name come from the `operationId` you provided for them in the OpenAPI files. Eg.`useGetUsersQuery` and `useGetUsersMutation`.

Note: While both hooks are generated for all endpoints, we recommend using queries for GET requests and mutations for POST/PUT/PATCH/DELETE requests.

They can be used in a very similar way like `useQuery` and `useMutation` from `@tanstack/react-query` but they provide:
- built-in `queryFn`s
- built-in `queryKey`s
- typed input parameters and outputs

To fetch the list of users from the above examples is as simple as:

```ts
const usersQuery = useGetUsersQuery();
//    ^- usersQuery.data: GetUsersListResponse | undefined
```

Or if your query has parameters they be passed as the first parameter:
```ts
const usersQuery = useGetUsersQuery({ offset: 15, limit: 10 });
```

3. Query options

Query options are available as the first or the second parameter of the query, depending on if the query has parameters or not.

```ts
const usersQuery = useGetUsersQuery({ refetchInterval: 5000 });
```

or
```ts
const usersQuery = useGetUsersQuery({ offset: 15, limit: 10 }, { refetchInterval: 5000 });
```

4. Managing query keys

You don't have to and also you can't provide `queryFn` or the `queryKey` options for use*Query hooks, as the SDK handles them automatically. You might still need to access the automatically generated query keys, so the SDK also exposes query key factories that you can use to refetch/invalidate query keys. This means that the SDK is the single source of the query keys in your app.

```tsx
const queryClient = useQueryClient();

queryClient.invalidateQueries({ queryKey: getUsersQueryKey.all() })

// or if your query has parameters
queryClient.invalidateQueries({ queryKey: getUsersQueryKey.withParams({ offset: 15, limit: 10 }) })
```

5. Disabled queries

Queries with parameters can also be disabled by providing `undefined` as a parameter for them. This set's `enabled` option to `false` under the hood for the query. This could help you to write dependent queries easier.

```ts
const accountsQuery = useGetAccountsQuery();
const accountId = accountsQuery.data?.at(0)?.id;

const reportsQuery = useGetReportsQuery(accountId && { accountId });
```

In this case `reportsQuery` is not running until `accountsQuery` finished fetching.

6. Passing headers to queries and mutations

`@tanstack/react-query` is not reposinble from what data sources you gather your data. This SDK does, it is deeply integrated with an underlaying API layer. So we added support to add headers to your requests.

```ts
// HEADERS is a JavaScript symbol provided by the SDK. By its unique nature it makes sure that it doesn't interfere with the other parameters you pass to your queries.
import { HEADERS } from '@project/oasg-example-react';

// Use with queries:
const usersQuery = useGetUsersQuery({
  [HEADERS]: {
    'X-Users-Feature-Flag': 'B',
  }
})

// With mutations - headers can be passed at the hook level:
const createUserMutation = useCreateUserMutation({
  [HEADERS]: {
    'X-Users-Feature-Flag': 'A',
  }
});

// Or while calling `mutate` or `mutateAsync`:
createUserMutation.mutate({
  createUserRequest: userData,
  [HEADERS]: {
    'X-Users-Feature-Flag': 'B',
  }
})

// Headers are merged in this order (later overrides earlier):
// 1. middleware configuration
// 2. mutation hook options
// 3. mutate/mutateAsync parameters
```

#### `stubby`

**When using Stubby, you must use the Supercharge's fork of the OpenApi Generator!**

```json
{
  "id": "client-stubby",
  "type": "stubby",
  "source": "source-merged",
  "generateWithDocker": "true",
  "repository": "registry.supercharge.io/misc/oasg-example"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| repository | URL of the Docker registry | N | - |
| generateWithDocker | Generate with docker | Y | - |

#### `spring`

Generates and published a Kotlin server side SDK using the `JavaSpring` OpenAPI Generator.

```json
{
  "id": "project-server",
  "source": "source-merged",
  "type": "spring",
  "artifactId": "project-api",
  "groupId": "com.project.api",
  "basePackage": "com.project.api",
  "mavenRepoUrl": "https://your-private-repo-url.com",
  "generatorCustomArgs": "--model-name-suffix=Dto"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| artifactId | Maven artifact identifier | Y | - |
| groupId | Maven group identifier | Y | - |
| basePackage | Name of the base Java package, model and api packages will be added under this one | Y | - |
| mavenRepoUrl | URL of the Maven repository to publish the artifacts to | Y | - |
| generatorCustomArgs | Pass-through OpenAPI Generator parameters, e.g.: `--model-name-suffix=Dto` | N | - |

#### `spring-kotlin`

Generates and published a Kotlin server side SDK using the `kotlin-spring` OpenAPI Generator.

```json
{
  "id": "project-server",
  "source": "source-merged",
  "type": "spring-kotlin",
  "artifactId": "project-api",
  "groupId": "com.project.api",
  "basePackage": "com.project.api",
  "mavenRepoUrl": "https://your-private-repo-url.com",
  "generatorCustomArgs": "--model-name-suffix=Dto"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| artifactId | Maven artifact identifier | Y | - |
| groupId | Maven group identifier | Y | - |
| basePackage | Name of the base Java package, model and api packages will be added under this one | Y | - |
| mavenRepoUrl | URL of the Maven repository to publish the artifacts to | Y | - |
| generatorCustomArgs | Pass-through OpenAPI Generator parameters, e.g.: `--model-name-suffix=Dto` | N | - |

#### `feign`

Generates and published a Kotlin server side SDK using the `JavaSpring` OpenAPI Generator with the `spring-cloud` library.

```json
{
  "id": "project-client",
  "source": "source-merged",
  "type": "feign",
  "artifactId": "project-client",
  "groupId": "com.project.client",
  "basePackage": "com.project.client",
  "mavenRepoUrl": "https://your-private-repo-url.com",
  "generatorCustomArgs": "--model-name-suffix=Dto"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| artifactId | Maven artifact identifier | Y | - |
| groupId | Maven group identifier | Y | - |
| basePackage | Name of the base Java package, model and api packages will be added under this one | Y | - |
| mavenRepoUrl | URL of the Maven repository to publish the artifacts to | Y | - |
| generatorCustomArgs | Pass-through OpenAPI Generator parameters, e.g.: `--model-name-suffix=Dto` | N | - |

#### `feign-kotlin`

TBD

#### `android`

```json
{
  "id": "client-android",
  "type": "android",
  "source": "source-merged",
  "packageName": "io.supercharge.oasg.example",
  "groupId": "io.supercharge.oasg.example",
  "artifactId": "client",
  "generatorCustomArgs": "--model-name-suffix=ApiModel",
  "formatter": "0.39.0",
  "formatterCustomArgs": "--disabled_rules=no-wildcard-imports,max-line-length",
  "repository": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/maven"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Java package name of the generated client | Y | - |
| groupId | Generated artifact package's organization | Y | - |
| artifactId | Generated artifact id  | Y | - |
| generatorCustomArgs | Custom arguments of the generator | N | - |
| formatter | `ktlint`: it can be a released version or a http(s) url | N | 0.39.0 |
| formatterCustomArgs | Custom arguments of the `ktlint` formatter | N | --disabled_rules=no-wildcard-imports,max-line-length |
| repository | URL of the Maven Repository | N | - |

#### `ios`

```json
{
  "id": "client-ios",
  "type": "ios",
  "generatorId": "swift5",
  "source": "source-merged",
  "projectName": "OASgExample",
  "repository": "git@gitlab.supercharge.io:example/openapi-generator-source.git",
  "interfaceType": "Combine",
  "generatorCustomArgs": "--model-name-suffix=ApiModel"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| projectName | Name of the project | Y | - |
| repository | URL of the generated client api code repository | Y | - |
| interfaceType | Response type of the generated client: `Combine` / `Result` / `RxSwift` / `AsyncAwait` / `PromiseKit` | Y | - |
| generatorCustomArgs | Custom arguments of the generator | N | - |

#### `apple-swift`

```json
{
  "id": "client-ios",
  "type": "apple-swift",
  "source": "source-merged",
  "projectName": "OASgExample",
  "repository": "git@gitlab.supercharge.io:example/openapi-generator-source.git",
  "generatorCustomArgs": ""
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| projectName | Name of the project | Y | - |
| repository | URL of the generated client api code repository | Y | - |
| generatorCustomArgs | Custom arguments of the generator | N | - |

#### `flutter`

```json
{
  "id": "client-flutter",
  "type": "flutter",
  "source": "source-merged",
  "packageName": "OASgExample",
  "repository": "git@gitlab.supercharge.io:example/openapi-generator-source.git",
  "generatorCustomArgs": "--model-name-suffix=ApiModel"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Name of the package | Y | - |
| repository | URL of the generated client api code repository | Y | - |
| generatorCustomArgs | Custom arguments of the generator | N | - |

#### `kmp`

```json
{
  "id": "client-kmp",
  "type": "kmp",
  "source": "source-merged",
  "packageName": "io.supercharge.oasg.example",
  "groupId": "io.supercharge.oasg.example",
  "artifactId": "client",
  "generatorCustomArgs": "--model-name-suffix=ApiModel",
  "formatter": "1.0.0",
  "formatterCustomArgs": "--disabled_rules=no-wildcard-imports,max-line-length,enum-entry-name-case",
  "repository": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/maven"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Kotlin package name of the generated client | Y | - |
| groupId | Generated artifact package's organization | Y | - |
| artifactId | Generated artifact id  | Y | - |
| generatorCustomArgs | Custom arguments of the generator | N | - |
| formatter | `ktlint`: it can be a released version or a http(s) url | N | 1.0.0 |
| formatterCustomArgs | Custom arguments of the `ktlint` formatter | N | --disabled_rules=no-wildcard-imports,max-line-length,enum-entry-name-case |
| repository | URL of the Maven Repository | N | - |

#### `python`

```json
{
  "id": "client-python",
  "type": "python",
  "source": "source-merged",
  "packageName": "oasg_example",
  "repositoryUrl": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/pypi"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Package nem for the project (convention: snake_case) | Y | - |
| repositoryUrl | URL of the PyPI repository | Y | - |
| projectName | Internal project name, inherits value of packageName (advised to keep the same) | N | $packageName |

Publishing the PyPI packages is done with Twine. For authentication against the PiPI repository you need to set the `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables.

#### `python-legacy`

```json
{
  "id": "client-python-legacy",
  "type": "python-legacy",
  "source": "source-merged",
  "packageName": "oasg_example",
  "repositoryUrl": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/pypi"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Package nem for the project (convention: snake_case) | Y | - |
| repositoryUrl | URL of the PyPI repository | Y | - |
| projectName | Internal project name, inherits value of packageName (advised to keep the same) | N | $packageName |

> ⚠️ Using Pydantic v1 for legacy reasons, this target will be discontinued.

Publishing the PyPI packages is done with Twine. For authentication against the PiPI repository you need to set the `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables.


#### `python-fastapi`

```json
{
  "id": "server-python",
  "type": "python-fastapi",
  "source": "source-merged",
  "packageName": "oasg_example",
  "repositoryUrl": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/pypi"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Package nem for the project (convention: snake_case) | Y | - |
| repositoryUrl | URL of the PyPI repository | Y | - |

Building the distribution package requires Flit.
Publishing the PyPI packages is done with Twine. For authentication against the PiPI repository you need to set the `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables.

#### `python-fastapi-raw-request`

```json
{
  "id": "server-python",
  "type": "python-fastapi-raw-request",
  "source": "source-merged",
  "packageName": "oasg_example",
  "repositoryUrl": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/pypi"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Package nem for the project (convention: snake_case) | Y | - |
| repositoryUrl | URL of the PyPI repository | Y | - |

Building the distribution package requires Flit.
Publishing the PyPI packages is done with Twine. For authentication against the PiPI repository you need to set the `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables.

#### `contract-testing`

```json
{
  "id": "example-project-contract-testing",
  "source": "example-project-api",
  "type": "contract-testing",
  "packageName": "@example-project/api-test",
  "repository": "https://gitlab.supercharge.io/api/v4/projects/1377/packages/npm/"
}
```
|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Package nem for the project | Y | - |
| repositoryUrl | URL of the PyPI repository | Y | - |

Client usage:
```bash
# install test dependencies
npm install --save-dev typescript@4.5.4 ts-node@10.4.0 mocha-simple-html-reporter@2.0.0 mocha@9.1.3 chai@4.3.4 @types/chai@4.3 @types/mocha@9.1
```

add tsconfig for tests (tsconfig.api-tests.json):
```json
{
  "compilerOptions": {
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "module": "commonjs"
  }
}
```

Generated package contains 2 main thing:
  * generated http requests
  * schema validator with request and response models

Known issues:
 * [openapi-typescript-validator-ext-ref](https://github.com/Kisfejes/openapi-typescript-validator) is a fork, should use the main package after external ref support PR is merged: https://github.com/Q42/openapi-typescript-validator/issues/11
 * Currently external $refs are resolved by copying its value to the main document -> no schema validators are generated for imported common open api schema definitions
 * there are some monkey patch (contract-testing/monkey-patch.sh) for `typescript-node` and `openapi-typescript-validator` which could be fixed in original package

Example test

```typescript
// auth.test.ts
import { describe, it } from 'mocha';
import { expect } from 'chai';

import { AuthApi, SLATypeEnumApiModel, example-projectErrorTypeEnumApiModel, UserTypeEnumApiModel, schemaValidator } from '@example-project/api-test'; // <---- generated models, validators are accessible through `schemaValidator` object

export const authApi = new AuthApi('https://backend.example.com/api');

describe('Auth', function () {
  it('login', async () => {
    const loginResponse = (
      await authApi.loginStart({
        contractNumber: '',
        userType: UserTypeEnumApiModel.Personal,
        birthDate: '',
      })
    ).body;
    // schema validation
    schemaValidator.StartLoginResponseApiModelDecoder.decode(loginResponse);
    // property value validation
    expect(loginResponse.slaType).to.be.equal(SLATypeEnumApiModel.SmsOtp);
    expect(loginResponse.secondaryAuthenticationMethod).to.be.equal(SLATypeEnumApiModel.ZipCode);
  });
});
```

```json
# package.json scripts
"scripts": {
  "api-test:all": "TS_NODE_PROJECT=tsconfig.api-tests.json mocha --timeout 10000 --reporter spec -r ts-node/register ./api-tests/tests/*.ts",
  "api-test:all:html": "TS_NODE_PROJECT=tsconfig.api-tests.json  mocha --timeout 10000 --reporter spec --reporter mocha-simple-html-reporter --reporter-options output=./api-tests/report/contract-test-report-$(date +%F_%H-%M).html -r ts-node/register ./api-tests/tests/*.ts",
  "api-test:feature": "TS_NODE_PROJECT=tsconfig.api-tests.json mocha --timeout 10000 -r ts-node/register",
}
```

#### `nestjs`

```json
{
  "id": "server-nestjs",
  "type": "nestjs",
  "source": "source-simple",
  "packageName": "@project/oasg-example-nestjs",
  "repository": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/npm/"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Name of the generated NPM package | Y | - |
| repository | URL of the NPM package registry | Y | - |

**Authorisation**<br>
The package generates an AuthGuard and applies it to endpoints where a security scheme is defined.

AuthGuard usage:
Implement the `AuthServiceInterface`, which will receive a validation request for each security scheme added to the checked endpoint and define the validation per scheme.
Finally provide the service in the context of the module the controller is defined in with the `AUTH_SERVICE_TOKEN` token.

If there is already an authorisation service setup for the controllers, the below dummy implementation could be used as a step over until full implementation.

```ts
@Module(
  providers:[
    {
      provide: AUTH_SERVICE_TOKEN,
      useValue: { validate: () => true },
    },
  ]
)
export class RootModule {}
```
Future improvements:
- with analyzing the request in the guard, only call the validation service with the relevant scheme (i.e: both ApiKey and Bearer Auth defined, but only API_KEY is present in the header, call only with ApiKey scheme )

**Known limitations:**
- array of enums in query/header/path/form parameters are not validated (stay as string)
- no multidimensional array validation in DTOs

**Validation availability:**
<br> _List is not comprehensive, missing items are definitely not supported currently_

Validations in General:
| Validation             | DTO | Query | Header | Path |
| ---------------------- | :-: | :---: | :----: | :--: |
| multidimensional array | ❌  |  ❌   |   ❌   |  ❌  |
| enum arrays            | ✅  |  ❌   |   ❌   |  ❌  |

Validations from OpenAPI spec:
| OpenApi Validation | Corresponding `class-validator` | DTO | Query | Header | Path | Workaround suggestion   |
| ------------------ | ------------------------------- | :-: | :---: | :----: | :--: | ----------------------- |
| **Common**         |                                 |     |       |        |      |                         |
| required           | IsDefined                       | ✅  |  ✅   |   ✅   |  ✅  |                         |
| !required          | IsOptional                      | ✅  |  ✅   |   ✅   |  ✅  |                         |
| **Types**          |                                 |     |       |        |      |                         |
| isBoolean          | IsBoolean                       | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isString           | IsString                        | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isNumber           | IsNumber                        | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isFloat            | IsNumber                        | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isDouble           | IsNumber                        | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isEnum             | IsEnum                          | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isArray            | IsArray                         | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isDate             | IsValidISO8601Date              | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isDateTime         | IsISO8601                       | ✅  |  ✅   |   ✅   |  ✅  |                         |
| **String**         |                                 |     |       |        |      |                         |
| pattern            | Matches                         | ✅  |  ✅   |   ✅   |  ✅  |                         |
| minLength          |                                 | ❌  |  ❌   |   ❌   |  ❌  | `pattern`               |
| maxLength          |                                 | ❌  |  ❌   |   ❌   |  ❌  | `pattern`               |
| isUuid             | IsUUID                          | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isUri              |                                 | ❌  |  ❌   |   ❌   |  ❌  | `pattern`               |
| isEmail            | IsEmail                         | ✅  |  ✅   |   ✅   |  ✅  |                         |
| **Number**         |                                 |     |       |        |      |                         |
| isInt              | IsInt                           | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isLong             | IsInt                           | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isShort            | IsInt                           | ✅  |  ✅   |   ✅   |  ✅  |                         |
| isUnboundedInteger |                                 | ❌  |  ❌   |   ❌   |  ❌  | `isInt`                 |
| minimum            | Min                             | ✅  |  ✅   |   ✅   |  ✅  |                         |
| maximum            | Max                             | ✅  |  ✅   |   ✅   |  ✅  |                         |


#### `openapi`

```json
{
  "id": "api-docs",
  "type": "openapi",
  "source": "source-simple",
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| fileName | Name of the generated file | N | `openapi.yaml` |

#### `dotnet`

```json
{
  "id": "dotnet",
  "type": "dotnet",
  "source": "source-merged",
  "sourceUrl": "https://api.nuget.org/v3/index.json",
  "apiKey": "apiKey",
  "packageName": "packageName",
  "generatorCustomArgs": "--global-property=supportingFiles,modelDocs --additional-properties=nullableReferenceTypes=false"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| sourceUrl | Url to where the package will be published | Y | - |
| apiKey | Api key of nuget source | Y | - |
| packageName | Name of the generated package | Y | - |
| generatorCustomArgs | Custom arguments of the generator (--global-property, --additional-properties) | N | - |

#### `dotnet-webapi`

```json
{
  "id": "dotnet-webapi",
  "type": "dotnet-webapi",
  "source": "source-merged",
  "sourceUrl": "https://api.nuget.org/v3/index.json",
  "apiKey": "apiKey",
  "packageName": "packageName",
  "generatorCustomArgs": "--global-property=supportingFiles,modelDocs --additional-properties=nullableReferenceTypes=false"
}
```

| Parameter           | Description                                                                    | Required | Default |
| ------------------- | ------------------------------------------------------------------------------ | -------- | ------- |
| sourceUrl           | Url to where the package will be published                                     | Y        | -       |
| packageName         | Name of the generated package                                                  | Y        | -       |
| apiKey              | Api key of nuget source (If not specified, provide the CI_JOB_TOKEN)           | N        | -       |
| generatorCustomArgs | Custom arguments of the generator (--global-property, --additional-properties) | N        | -       |

> **Nullable object/enum references.** A property spec'd nullable as a
> reference to a named schema — `nullable: true` alongside a `$ref` (OpenAPI
> 3.0, typically via an `allOf` wrapper) or `oneOf: [$ref, {type: 'null'}]`
> (OpenAPI 3.1) — now generates a nullable C# type (`Category?`), matching the
> TypeScript targets' `Category | null`, regardless of whether the property is
> `required`: `required` only governs presence of the key, never nullness of
> the value. Previously only *optional, non-nullable* references got a `?`;
> nullable references (required or not) silently generated a non-nullable
> type, forcing consumers to suppress with `null!` and losing the compiler's
> null-reference warnings at the point of use.
>
> Nullable **containers** (arrays, maps) are unaffected by this change and
> still generate a non-nullable collection type.
>
> This applies to the `dotnet`, `dotnet-webapi` and
> `dotnet-webapi-system-text-json` targets. `dotnet-system-text-json`
> (`generichost`) already handled this correctly. To opt out entirely, disable
> nullable reference types via `generatorCustomArgs`:
> `--additional-properties=nullableReferenceTypes=false`.

#### `dotnet-system-text-json`

An AOT-oriented C# **client library**. Unlike `dotnet` (which uses the
`csharp-functions` generator and produces an Azure Functions app serialized with
Newtonsoft.Json), this target uses the `csharp` generator's `generichost`
library: an `HttpClient` + .NET Generic Host (dependency-injection) **host API**,
serialized with **System.Text.Json source generation** (a `JsonSerializerContext`
per model — no Newtonsoft, no reflection-based serialization).

The generated project targets **.NET 10** and is marked
`<IsAotCompatible>true</IsAotCompatible>`, so the trim/AOT analyzers run against
consumers.

```json
{
  "id": "dotnet-system-text-json",
  "type": "dotnet-system-text-json",
  "source": "source-merged",
  "sourceUrl": "https://api.nuget.org/v3/index.json",
  "apiKey": "apiKey",
  "packageName": "packageName"
}
```

| Parameter           | Description                                                                    | Required | Default |
| ------------------- | ------------------------------------------------------------------------------ | -------- | ------- |
| sourceUrl           | Url to where the package will be published                                     | Y        | -       |
| apiKey              | Api key of nuget source                                                        | Y        | -       |
| packageName         | Name of the generated package                                                  | Y        | -       |
| generatorCustomArgs | Custom arguments of the generator (--global-property, --additional-properties) | N        | -       |

> **AOT status — AOT-capable, not certified warning-clean.** Newtonsoft is gone
> and every generated **model** has a source-generated `JsonSerializerContext`,
> which is the core requirement for trimming/Native AOT. However, the upstream
> `generichost` serialization is a deliberate **hybrid**: the JSON options
> combine the source-gen model contexts with a reflection
> `DefaultJsonTypeInfoResolver()` fallback (plus a reflection
> `JsonStringEnumConverter`) to handle types the contexts don't cover —
> `List<T>` responses, dictionaries, primitives, enums. Because of that fallback
> the build emits `IL2026`/`IL3050` trim/AOT analyzer warnings.
>
> These warnings are inherent to the generator (unchanged through 7.17.0), not
> something a template override fixes cleanly: removing the fallback would break
> at runtime for any uncovered type, and routing calls so the analyzer goes
> quiet would only hide that risk. So a consumer can use this package and its
> source-gen model paths are AOT-safe, but a full Native-AOT publish is **not
> guaranteed** for every spec shape. `<IsAotCompatible>true</IsAotCompatible>`
> is set so consumers see those analyzer warnings rather than discovering the
> gaps at runtime.

#### `dotnet-webapi-system-text-json`

A server-stub library (`aspnetcore` generator, `buildTarget=library`) serialized
with **System.Text.Json**, targeting **.NET 10** and marked
`<IsAotCompatible>true</IsAotCompatible>`. Operations are exposed as
**minimal-API endpoints** (Native-AOT compatible) rather than MVC controllers.

```json
{
  "id": "dotnet-webapi-system-text-json",
  "type": "dotnet-webapi-system-text-json",
  "source": "source-merged",
  "sourceUrl": "https://api.nuget.org/v3/index.json",
  "apiKey": "apiKey",
  "packageName": "packageName"
}
```

| Parameter                   | Description                                                                    | Required | Default |
| --------------------------- | ------------------------------------------------------------------------------ | -------- | ------- |
| sourceUrl                   | Url to where the package will be published                                     | Y        | -       |
| packageName                 | Name of the generated package                                                  | Y        | -       |
| apiKey                      | Api key of nuget source (If not specified, provide the CI_JOB_TOKEN)           | N        | -       |
| withWolverineImplementation | Make the minimal-API endpoints invoke Wolverine directly (see below)           | N        | `false` |
| generatorCustomArgs         | Custom arguments of the generator (--global-property, --additional-properties) | N        | -       |

> **Minimal API + Native AOT.** A single `EndpointRouteBuilderExtensions.cs`
> (generated once via a `files` SupportingFiles template) holds an `I{ApiName}`
> interface per API, a `Map{ApiName}Endpoints()` per API, and an aggregate
> `MapAll{PackageName}Endpoints()` that calls them all — mapping the operations as
> minimal-API endpoints delegating to the DI-resolved implementation. The host
> implements each `I{ApiName}` and calls `app.MapAll{PackageName}Endpoints()`; the
> abstract MVC controllers are suppressed.
>
> The package builds AOT-clean: it sets `<EnableRequestDelegateGenerator>` so the
> minimal-API `Map*()` calls are statically generated (no reflection-based request
> delegates), each model emits a source-generated `JsonSerializerContext` used by
> its `ToJson()` (no Newtonsoft, no reflection `JsonSerializer`), and there is no
> reflection-based enum converter. Building the package under the AOT analyzer
> (`<IsAotCompatible>`) raises no IL2026/IL3050 warnings.
>
> Enums (de)serialize by their wire value (e.g. `"available"`): each generated enum
> carries `[JsonConverter(typeof(JsonStringEnumConverter<T>))]` with per-member
> `[JsonStringEnumMemberName]`, which the source generator honours.
>
> **JSON registration.** The package generates a `{PackageName}JsonSerializerContext`
> (a source-generated `JsonSerializerContext` over every model, request/response type
> and inline enum) plus an `Add{PackageName}JsonOptions()` extension that registers it
> on the minimal-API JSON resolver chain. Call it in Program.cs:
>
> ```csharp
> builder.Services.Add{PackageName}JsonOptions();
> ```
>
> This is **required when the host is published with Native AOT** (`PublishAot=true`),
> because AOT removes the reflection JSON fallback and the endpoints must resolve every
> DTO through source generation. For a reflection-based (JIT) host it is harmless (the
> reflection resolver already covers everything), but registering it still gives faster,
> allocation-free metadata, so calling it unconditionally is recommended.

##### `withWolverineImplementation`

When `true`, the generated minimal-API endpoints invoke [Wolverine](https://wolverinefx.net)
**directly** instead of delegating to the `I{ApiName}` interfaces — there are no
`I{ApiName}` interfaces in this mode. The single `EndpointRouteBuilderExtensions.cs`
instead contains:

- **A request wrapper per operation** — `public record AddPetRequest(Pet pet);`,
  `public record GetPetByIdRequest(long petId);`, etc. Each bundles **all** of the
  operation's parameters (path, query, header, body), so two operations never
  collide on a shared request/response type and every parameter is carried
  (including for file uploads).
- **`Map{ApiName}Endpoints()`** (one per API), plus an aggregate
  **`MapAll{PackageName}Endpoints()`** that calls them all — each endpoint invokes
  the request through Wolverine and returns the result:
  ```csharp
  endpoints.MapPost("/api/v3/pet",
      async ([FromBody] Pet pet, [FromServices] IMessageBus messageBus, CancellationToken ct) =>
          Results.Ok(await messageBus.InvokeAsync<Pet>(new AddPetRequest(pet), ct)));
  ```
  Operations with no response body return `Results.NoContent()`; secured
  operations get `.RequireAuthorization()`.
- **`ConfigureWolverineMessaging(this WolverineOptions options, string localQueueName = "PackageName")`** —
  one method that routes every request type in the assembly to a local queue (the
  queue name is a parameter).

The `WolverineFx` package reference is added automatically.

**Host wiring** the consumer provides:

```csharp
builder.Host.UseWolverine(opts =>
{
    opts.ConfigureWolverineMessaging();            // or pass a custom queue name

    // Static codegen (see below). Pre-generate with `dotnet run -- codegen write`.
    opts.CodeGeneration.TypeLoadMode = JasperFx.CodeGeneration.TypeLoadMode.Static;
});

var app = builder.Build();
app.MapAll{PackageName}Endpoints();                // aggregate; or call Map{ApiName}Endpoints() individually
```

The host also provides a **handler for each `*Request` type** (Wolverine discovers
them by convention), e.g. `public Task<Pet> Handle(AddPetRequest request) { ... }`.

**Static codegen.** Set `TypeLoadMode.Static` in the host (above) so Wolverine
does **not** compile handler code at runtime, and pre-generate it as part of your
build/deploy, e.g. `dotnet run -- codegen write` (or, to opt back into runtime
compilation, drop that line and reference `WolverineFx.RuntimeCompilation`).

**No retries / error handling.** Wolverine scopes retry rules per message type on
the **handler**, not on the routing options, so `ConfigureWolverineMessaging`
does not set a retry policy. Disable retries per handler where you want
fail-fast, e.g.:

```csharp
public static class AddPetRequestHandler
{
    public static void Configure(HandlerChain chain) => chain.OnAnyException().Discard();
    public Task<Pet> Handle(AddPetRequest request) { ... }
}
```

With no retries, a handler exception propagates straight back through
`InvokeAsync` into the endpoint, where you map it to an HTTP response host-side
(`IExceptionHandler` + `AddProblemDetails()`).

> **File uploads.** The wrapper carries every parameter, so a file operation's
> path/query parameters reach the handler alongside the body (unlike sending the
> body alone). The body itself is carried as a `System.IO.Stream`, which works
> for the in-process local-queue routing used here (passed by reference). A
> `Stream` is **not** serializable, so if you re-route these requests to a remote
> transport (RabbitMQ, Azure Service Bus, …) the file body would not serialize —
> buffer it to a `byte[]` in that case.

#### `postman`

```json
{
  "id": "postman-collection",
  "type": "postman",
  "source": "source-simple",
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| fileName | Name of the generated file | N | `collection.json` |

#### `typescript-axios`

```json
{
  "id": "client-typescript-axios",
  "type": "typescript-axios",
  "source": "source-merged",
  "packageName": "@project/oasg-example-typescript-axios",
  "repository": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/npm/"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Name of the generated NPM package | Y | - |
| repository | URL of the NPM package registry | Y | - |

#### `typescript-fetch`

```json
{
  "id": "client-typescript-fetch",
  "type": "typescript-fetch",
  "source": "source-merged",
  "packageName": "@project/oasg-example-typescript-fetch",
  "repository": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/npm/"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Name of the generated NPM package | Y | - |
| repository | URL of the NPM package registry | Y | - |

#### `msw`

```json
{
  "id": "msw",
  "type": "msw",
  "source": "source-merged",
  "packageName": "@project/oasg-example-msw",
  "repository": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/npm/"
}
```

|Parameter| Description| Required | Default |
|-|-|-|-|
| packageName | Name of the generated NPM package | Y | - |
| repository | URL of the NPM package registry | Y | - |

**Usage**<br>

1. Configure the SDK

Start by configuring the SDK with a `baseUrl` and an optional `delay`:

```ts
import { setMswSdkConfig } from '@project/oasg-example-msw';

setMswSdkConfig({
  baseUrl: 'https://your-api-url.domain',
  // each request will take at least 100ms and at most 400ms (this is the default)
  // disable delay by setting it to [0, 0]
  delay: [100, 400],
});
```

2. Mock your endpoints

Once configured, you can start mocking your endpoints.
The SDK automatically sets up the handlers and enforces fully typed params, query params, request bodies, and responses based on your OpenAPI spec.

```ts
import { setupWorker } from 'msw/browser';
import { HttpReponse } from 'msw';
import { mockUsersApi, type User } from '@project/oasg-example-msw';

const mockUsers: User[] = [
  {
    id: crypto.randomUUID(),
    firstName: 'Chester',
    lastName: 'Bennington',
    createdAt: new Date(),
  },
  {
    id: crypto.randomUUID(),
    firstName: 'Emily',
    lastName: 'Armstrong',
    createdAt: new Date(),
  }
];

setupWorker(
  // each tag in your OpenAPI spec exposes a `mock{ApiName}Api` helper
  ...mockUsersApi({
    // provide the endpoints you want to mock by their `operationId`
    getUsers: (info) => {
      return HttpResponse({
        items: info.queryParams.sortDirection === 'desc'
          ? mockUsers.toSorted((a, b) => a.createdAt - b.createdAt)
          : mockUsers.toSorted((a, b) => b.createdAt - a.createdAt),
      })
    },
    createUser: (info) => {
      const user = await info.request.json();
      mockUsers.push({
        id: crypto.randomUUID(),
        createdAt: new Date(),
        ...user,
      });

      return HttpResponse(null, { status: 201 });
    }
  }),
)
```

---

# Migration Guide

This section covers the breaking changes and their migrations across major version upgrades.

## From `19.x.x` to `20.0.0`

From this version _OASg_ requires `node` version `>=24.21` (the current LTS line) and `npm` version
`>=11` by default. `node@20` reached its end of life, so please upgrade your projects accordingly.

The `stubby` target's generated `Dockerfile` is based on `node:24.21.0-alpine` as well.

A 7 day [dependency install cooldown](#dependency-install-cooldown) now applies to every
`npm install` _OASg_ runs, including the ones the `npm` based targets perform while building the
generated SDK. A target that must pick up a release younger than that needs
`NPM_CONFIG_MIN_RELEASE_AGE: "0"` on its job.

### Peer dependencies in the `npm` based targets

Framework packages that belong to the consuming application are declared as `peerDependencies`
instead of being pinned by the generated SDK, so the application decides which version is used:

* `typescript-axios`: `axios` moved from `dependencies` to `peerDependencies` (`^1.6.1`).
  Applications that relied on the SDK to pull `axios` in have to depend on it themselves.
* `angular`: `@angular/common` is declared as a peer next to `@angular/core` and `rxjs`, as the
  generated services import `HttpClient` from `@angular/common/http`.
* `nestjs`: `reflect-metadata` is `^0.2.2` rather than the exact `0.2.2`, `@types/multer` became an
  optional peer (it is only needed for `binary` payloads), and the pinned `@types/validator` is no
  longer shipped as a runtime dependency, since `class-validator` already depends on it.
* `react`: `@tanstack/react-query` is `^5.90.21` rather than the exact `5.90.21`, so any _React
  Query_ `5.x` can be used. The generated hooks take `NoInfer` from TypeScript instead of from
  `@tanstack/react-query`, which stopped re-exporting it in `5.10x`, so they need TypeScript `>=5.4`.

The `msw` target already declared `msw` as a peer, and `typescript-fetch` has no runtime dependency
at all, so neither of them changed.

## From `18.x.x` to `19.0.0`

### Breaking in `spring`, `spring-kotlin`, `feign` and `feign-kotlin` targets

SDK jars produced by these targets now target **Spring Boot 4** and **Jackson 3**, which moved to
the new `tools.jackson` group. Consumers must upgrade accordingly, or pin the previous baseline via
`generatorCustomArgs` in their _OASg_ `config.json`:

```json
"generatorCustomArgs": "-puseSpringBoot3=true -puseSpringBoot4=false -puseJackson3=false -popenApiNullable=true"
```

### Breaking in `spring` and `feign` targets

`openApiNullable` is now disabled, as the `jackson-databind-nullable` library behind it is Jackson 2
only. `nullable: true` properties are generated as plain types instead of `JsonNullable<T>`.

### Breaking in `spring-kotlin` and `feign-kotlin` targets

API interface methods have no default implementation anymore and fail compilation unless the consumer
overrides them. To keep the previous behaviour, set `skipDefaultInterface=false` back via
`generatorCustomArgs` in your _OASg_ `config.json`.

## From `18.2.x` to `18.3.0`

These changes shipped in `18.3.0` with the update to _OpenAPI Generator_ `7.22.0`.

### Breaking in `spring-kotlin` and `feign-kotlin` targets

1. `oneOf` schemas with a `discriminator` are now generated as a Kotlin `sealed interface` declaring
   only the discriminator property, so subtype properties have to be reached by narrowing with `is`.
2. Projects overriding `model.mustache` via `templateDir` must re-fork it — it changed significantly
   upstream. See [Template Customization](#template-customization).

### Breaking in `feign` and `feign-kotlin` targets

The generated client configuration classes (`ClientConfiguration`, `ApiKeyRequestInterceptor`, and
`ClientPropertiesConfiguration` for OAuth specs) moved from the shared
`org.openapitools.configuration` package to `<basePackage>.config`, so clients no longer overshadow
each other in projects consuming several of them. Update your imports accordingly.

## From `17.x.x` to `18.0.0`

### Breaking in `react` target

1. Exported hooks were renamed. API names are not part of the hooks anymore as `operationId` is unique by itself. E.g. instead of `useUsersApiCreateUserMutation` the name is `useCreateApiMutation`.
2. *Query keys* are now managed by the SDK itself and they were removed from the query's options object. Check the *Managing query keys* section below to get an idea of how you can still work with query keys in your application.
3. If an endpoint has URL parameters, search parameters, or a body, it is now the first parameter of the `use*Query` hooks. E.g. instead of `useGetUserList({ refetchInterval: 60_000 }, { limit, offset })` it is `useGetUserList({ limit, offset }, { refetchInterval: 60_000 })`. This especially comes in handy together with the automatic queryKey management the SDK provides, as without the queryKey there are no required parameters in the query's options object, so you can completely ignore it if you don't want to set any options. E.g. instead of `useGetUserList({}, { limit, offset })` it is `useGetUserList({ limit, offset })` now.

## From `16.x.x` to `17.0.0`

From this version _OASg_ requires `node` version `^20.19` by default. Please upgrade your projects accordingly.

## From `15.x.x` to `16.0.0`

### Breaking in `nestjs` target

In the `nestjs` target the `AuthServiceInterface` needed to be implemented in projects got changed from:

```typescript
validate: (scheme: SecurityScheme, request: any) => boolean | Promise<boolean> | Observable<boolean>;
```

to

```typescript
validate: (scheme: SecurityScheme, context: ExecutionContext) => boolean | Promise<boolean> | Observable<boolean>;
```

in order to provide compabilitity with existing Nest guards

### Breaking in `python` target

From this version the `python` target got renamed to `python-legacy` to reflect the same changes in __OpenAPI Generator__ where starting from version 7.1.0 the `python-pydantic-v1` generator outputs the "legacy compatible" code, and the ongoing `python` generator got updated to support Pydantic v2.


## From `14.x.x` to `15.0.0`

In this version the `nestjs` generator has been upgraded to support verifying different security schemes from generated code. This means that a new [Guard](https://docs.nestjs.com/guards) has been introduced on the API oprerations which need to be implemented and checks for valid authentication credentials.

If you wish to change your authentication handling at a later date, use the [dummy implementation](#nestjs) mentioned above in the documentation.

## From `13.x.x` to `14.0.0`

Several dependencies have been upgraded, and OASg now uses `node` version 20.15.0 and `npm` version 10 by default. If your project still uses `node@18`, you should upgrade first.

## From `12.x.x` to `13.0.1`

> ❗ Due to version `13.0.0` has been published before erroneously (then unpublished) to the NPM registry, this version of the artifact won't be available either as an NPM package or a Docker base image. Please use the `13.0.1` patch version instead.

### Schema naming updates in `angular`, `python`, `android`,`ios`, `nestjs`, `react` targets

With the update to [OpenAPI Generator 7.0.0](https://github.com/OpenAPITools/openapi-generator/releases/tag/v7.0.0) the same breaking changes appear as in other targets before:

* [Inline Schema Naming in `spring-kotlin`, `spring` and `feign`](#inline-schema-naming-in-spring-kotlin-spring-and-feign)
* [Skip Reusing Schemas in `spring-kotlin`, `spring` and `feign`](#skip-reusing-schemas-in-spring-kotlin-spring-and-feign)

and more:

* `ARRAY_ITEM_SUFFIX` and `MAP_ITEM_SUFFIX` variables has been set to empty strings
  - generated inline classes won't have the default `...Inner` suffix from now on

### Breaking in `angular` target

* the default `ngVersion` parameter is set to `16.0.0` if you wish to specify another version, use e.g `"generatorCustomArgs": "-p ngVersion=12"` in your `config.json`

### Breaking in `react-native` target

* as both technologies used the same `typescript-fetch`-based generator, with this version the previous `react-native` target has been renamed to a more generic `react` name
  - if at the future the best practices would change between the web-based _React_ and _React Native_ mobile projects, the `react-native` target will be reintroduced
* enum key with multiple segments will contain underscores e.g. the enum key generated from the `value_one` value was used to be `VALUEONE`, this will become `VALUE_ONE` after the update

## From `11.x.x` to `12.0.0`

The following options from the `openapi` target type has been moved to the [Source](#source) configuration.

* `bundle`
* `sortSchemas`
* `decorators`
* `cleanup`

Please update your `config.json` accordingly: move these properties - if they exist - to the respective `source` configuration.

> ⚠️ As the `bundle`, `sortSchemas` and `cleanup` flags are **enabled by default**, even without using custom decorators some normalization steps are applied to the source specification before generating the targets. If this causes any problems in your project (although highly unlikely it will) consider **disable** these flags.

## From `10.x.x` to `11.0.0`

### Linting

The linter configuration previously stored in `.spectral.yaml` needs to be updated to the JS format:

1. rename the file to `.spectral.js` (don't forget to update `spectral.rulesetFile` in `.vscode/settings.json` if used!)
2. follow the [instructions](#configure-linter) for extending the base _OASg_ ruleset in JS
3. migrate project-specific custom [rules](#custom-rules) and [functions](#custom-functions) to JS format

The typical minimal configuration from this in YAML

  ```yaml
  extends: '@team-supercharge/oasg/rules/default.yaml'
  ```

must become this in JS (if no custom rules or functions are used):

  ```js
  import oasgRuleset from '@team-supercharge/oasg/ruleset';

  export default {
    extends: oasgRuleset
  }
  ```

## From `9.x.x` to `10.0.0`

### Changed configuration in `android`

  - `projectName` parameter was removed (it was actually unused)
  - `groupId` and `artifactId` parameter were added

## From `8.x.x` to `9.0.0`

### Skip Reusing Schemas in `spring-kotlin`, `spring` and `feign`

The newer versions of OpenAPI Generator adds the flag to skip the [automatic inline schema reusing](https://openapi-generator.tech/docs/customization/#inline-schema-naming) logic (see example what this means below).

From _OASg_ 9.0.0 the **default and recommended behaviour is to skip schema reusing** for the targets above. If you wish to resume schema reusing for compatibility reasons, add `--inline-schema-name-defaults SKIP_SCHEMA_REUSE=false` to `generatorCustomArgs` in the project's `config.json`

Take the following schema:

  ```yaml
  schemas:
    Message:
      type: object
      properties:                 # messages have a topic and text
        topic:
          type: object
          properties:             # topics have id and name
            id:
              type: string
            name:
              type: string
        text:
          type: string

    User:
      type: object
      properties:                 # users have a company, and firstName and lastName
        company:
          type: object
          properties:             # companies have id and name
            id:
              type: string
            name:
              type: string
        firstName:
          type: string
        lastName:
          type: string
  ```

Previously the following DTO objects were generated from this schema:

```java
Message(MessageTopic topic, String text)
MessageTopic(String id, String name)
User(MessageTopic company, String firstName, String lastName)
```

Previously the generator reused internal schemas which had the exact same fields, ending up with a `MessageTopic` object for the users' Company, just because both had `id` and `name` string properties.

With defining `SKIP_SCHEMA_REUSE=true` the output will be more verbose, but schema names won't get mixed up:

```java
Message(MessageTopic topic, String text)
MessageTopic(String id, String name)
User(UserCompany company, String firstName, String lastName)
UserCompany(String id, String name)
```

## From `7.x.x` to `8.0.0`

### Linting

If you plan to use the _OASg_ base image with the preinstalled `oasg` binary without installing npm dependencies on CI, make sure you update your `.spectral.yaml` from the previously recommended syntax which picked up the rules directly from the file system:

  ```yaml
  extends: node_modules/@team-supercharge/oasg/rules/default.yaml
  ```

to use the syntax which picks up rules from the npm package wherever it's installed:

  ```yaml
  extends: '@team-supercharge/oasg/rules/default.yaml'
  ```

### Spring Boot 3 support in `spring-kotlin`, `spring` and `feign`

Spring Boot 3 version is the default for these generators. To generate Spring Boot 2 libraries, add `-puseSpringBoot3=false` to `generatorCustomArgs` in the projects `config.json`

From **OASg 8.0.0** the recommended way is to use the base image matching OASg version from the `registry.gitlab.com/team-supercharge/oasg` registry. The images use JDK 17 by default. If the generated API must support Java 11, then add the following snippet to the build job:

  ```yaml
  before_script:
    - update-java-alternatives -s temurin-11-jdk-amd64
  ```

### Inline Schema Naming in `spring-kotlin`, `spring` and `feign`

Generating names of inline schemas works differently in the updated [openapi-generator](https://openapi-generator.tech/) version `6.3.0` which is now used in the targets above. If you used inline and/or nested schemas the generated artifact **might break** you project and you need to rename your schemas.

Take the following schema:

```yaml
schemas:
  Message:
    type: object
    properties:                 # messages have topics and a text
      topic:
        type: object
        properties:             # topics have id and array of tags
          id:
            type: string
          tags:
            type: array
            items:
              type: object
              properties:       # tags have a name
                name:
                  type: string
      text:
        type: string
```

Previously the following DTO objects were generated from this schema:

```java
Message(MessageTopic topic, String text)
MessageTopic(String id, List<MessageTags> tags)
MessageTags(String name)
```

With the updated (correct) schema naming convention the result will be the following:

```java
Message(MessageTopic topic, String text)
MessageTopic(String id, List<MessageTopicTags> tags)
MessageTopicTags(String name)
```

## From `6.x.x` to `7.0.0`

Only effects the `stubby` target. Whether a Docker image is needed to be generated from the output, it needs to be explicitly configured using the new `generateWithDocker` parameter.

## From `4.x.x` to `5.0.0`

If you used the `-t <template directory>` flag in your `generatorCustomArgs` for any target, please refer to the newly introduced [Template Customization](#template-customization) section for the correct way of doing it.

For older Angular versions it was necessary to install the `typescript@3.9.5` package with fixed version. For newer version of Angular this workaround was actually making the generator to fail, so it got removed. If you want to use OASg 5.0.0 with an older Angular version please consider updating it, or patching the previous fix.

## From `3.x.x` to `4.0.0`

Starting from version `4.0.0` OASg became open-source. Thus future packages are (only) available from the official npmjs.org registry without any authentication.

Please take the following steps:

* update the package reference from `@misc/oasg` to `@team-supercharge/oasg` in your project's `package.json`
* bump the version used form `3.x.x` to `4.0.0` to find the valid package
* remove any additional authentication steps for the `@misc` Supercharge-specific namespace (if no other package is used from it)
* run `npm i` to update your `package-lock.json`

## From `2.x.x` to `3.0.0`

Follow the steps:

* locate `.spectral.yaml` in your root project folder => it is a symlink inside `node_modules/@misc/oasg...`
* delete the symlink and set up the new linting process according to the [Configure linter](#configure-linter) section
  - create file `.spectral.yaml` in project root
  - use the `extends` syntax to refer to the default configuration

Your project can break for two reasons:

1. newer version of Spectral enforces some new rules that were not previously enforced (e.g example types should match the type of the property)
2. starting from 3.0.0 and the linter configuration above _OASg_ enforces new [Custom rules](#custom-rules) as well - if you cannot update your project consider turning off the new rules

---

# Roadmap

- ~~implement lint command with [spectral](https://github.com/stoplightio/spectral) modules for validation & linting~~
- ~~serve command (local express server to circumvent CORS) with [swagger-ui-express](https://www.npmjs.com/package/swagger-ui-express)~~
- add `-w --watch` flag to lint and serve commands for local development
- ~~research multi-file specs (domain models), theoretically should work~~
- ~~implement default GitLab CI jobs~~
- ~~add merger functionality~~
- ~~add forked openapi-generator somehow~~
- ~~add editorconfig~~
- ~~disallow special characters in source/target IDs (only allow letters, numbers, underscore, dash)~~
- ~~check for dependencies on startup (java, wget, jq)~~
- handle API versioning in OpenAPI files:
  * use bumpFiles functionality in [standard-version](https://github.com/conventional-changelog/standard-version#bumpfiles-packagefiles-and-updaters)
  * get all input files from "config.sources" array
  * change version in YAML without touching/reformatting the whole file
- improve README with documenting:
  * ~~getting started section~~
  * ~~configuration (in projects)~~
  * ~~CI setup (in projects)~~
  * ~~override linter rules (default set + extend OASG ruleset)~~
  * contributing guideline (e.g. extending config schema)

---
_Source: https://npm.io/package/@team-supercharge/oasg · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
