@team-supercharge/oasg

OASg - Open Api Spec generator

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

• Getting Started
  • Required Tools
  • Initialize API Repo
  • Create .config.json
  • Configure Linter
  • Use with Docker
  • Use with GitLab CI
• Version Overview
• Usage
• Linter Rules
  • Custom Rules
  • Custom Functions
• Template Customization
• Configuration
  • Source
    • Source Types
    • Overrides
  • Target
    • Target Types
• Migration Guide
• 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.

{
    "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:

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

For detailed configuration instructions please refer to the Configuration section below.

Configure Linter

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

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

export default {
  extends: oasgRuleset
};

The file is used for configuring 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 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

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:

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 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:

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:

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.

Component
Internal	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1
Core
Linter
Client Targets	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	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	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. If no target specified, all targets will be linted.

$ npx oasg lint [source]

serve

Bundles the specified source and serves with Swagger UI, hooked up internally with a local proxy server to circumvent CORS limitations.

$ npx oasg serve [source]

proxy

Fires up a 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.

$ npx oasg proxy [source] --server

or

$ npx oasg proxy [source] -s

generate

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

$ npx oasg generate [target]

publish

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

$ 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.

$ npx oasg save-lock [target]

---

Linter Rules

OASg makes use of the awesome 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 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 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 using the rules: property.

An example configuration can be found here:

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
      }
    }

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 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:

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

• 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 and copy the original template 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 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:

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

// 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.

{
  "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.

{
  "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 which values are required.

"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

{
  "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

{
  "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

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.

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>
  );
};

1. 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 queryFns
• built-in queryKeys
• typed input parameters and outputs

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

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

Or if your query has parameters they be passed as the first parameter:

const usersQuery = useGetUsersQuery({ offset: 15, limit: 10 });

1. 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.

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

or

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

1. 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.

const queryClient = useQueryClient();

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

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

1. 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.

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.

1. 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.

// 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!

{
  "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.

{
  "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.

{
  "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.

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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	-

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

{
  "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	-

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

{
  "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

{
  "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

{
  "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:

# 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):

{
  "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 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

// 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);
  });
});

# 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

{
  "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
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.

@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:
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

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

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

dotnet

{
  "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

{
  "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	-

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.

{
  "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.

{
  "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:

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 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:

  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:

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.:

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

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

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

typescript-axios

{
  "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

{
  "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

{
  "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

1. Configure the SDK

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

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],
});

1. 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.

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 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:

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

to

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 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 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 the same breaking changes appear as in other targets before:

• Inline Schema Naming 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 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 for extending the base OASg ruleset in JS
3. migrate project-specific custom rules and functions to JS format

The typical minimal configuration from this in YAML

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

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

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 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:

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:

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:

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:

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:

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:

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 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:

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:

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:

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 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 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 as well - if you cannot update your project consider turning off the new rules

---

Roadmap

• implement lint command with spectral modules for validation & linting
• serve command (local express server to circumvent CORS) with 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
  • 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)