devexperts / swagger-codegen-ts

Typesafe Swagger API generator for TypeScript

Typesafe OpenAPI generator for TypeScript

Features

• Generates client code from OpenAPI 3.0, 2.0 (aka Swagger) and AsyncAPI specs
• Pluggable HTTP clients: can use fetch, Axios or any other library
• Flexible response types: works with Promises and reactive streams like RxJS
• Runtime type checks: validates server responses against the spec
• Written in pure TypeScript using fp-ts and io-ts libraries

Demo code

The examples below refer to the Pet Store OpenAPI 3.0 schema.

After running the codegen, interacting with a REST API may be as simple as this:

import { petController as createPetController } from "./src/generated/petstore.json/paths/PetController";
import { Pet } from "./src/generated/petstore.json/components/schemas/Pet";

// Creating a controller, see the "HTTP Clients" wiki page for more details
const petController = createPetController({ httpClient: fetchHttpClient });

// The returned object is guaranteed to be a valid `Pet`
const createdPet: Promise<Pet> = petController.addPet({
  body: {
    // The parameters are statically typed, IntelliSense works, too
    name: "Spotty",
    photoUrls: [],
  },
});

More usage scenarios are supported - check the usage page for more detail.

Installation

1. Make sure the peer dependencies are installed, then install the codegen itself:

   yarn add typescript fp-ts io-ts io-ts-types
   yarn add -D @devexperts/swagger-codegen-ts
   

2. Create a console script that would invoke the generate function, passing the options such as path to the schema file and the output directory. See the Generators page for the API reference, and examples/generate for sample scripts.

3. In most cases, you might want to include the code generation step into the build and local launch scripts. Example:

   /* package.json */
   
     "scripts": {
   +   "generate:api": "ts-node scripts/generate-api.ts",
   -   "start": "react-scripts start",
   +   "start": "yarn generate:api && react-scripts start",
   -   "build": "react-scripts build"
   +   "build": "yarn generate:api && react-scripts build"
     }

Contributing

• Feel free to file bugs and feature requests in GitHub issues.
• Pull requests are welcome - please use Conventional Commits.

Please read the Contributors Guide for more information.

swagger-codegen-ts's Issues

Fix generation of entities with the same name in one file

components:
  schemas:
    echo:
      description: echo
      type: string
  messages:
    echo:
      payload:
        $ref: '#/components/schemas/echo'

This piece will result in

import { echo, echoIO } from '../../components/schemas/echo';

export type echo = echo;
export const echoIO = echoIO;

We need to find a way to avoid such conflicts. Possibly using named imports.

Remove all paths from configuration

• replace pathsToSpec with a list of parsed spec objects

  • supports any spec format, not only json/yaml)
  • support for specs loaded from network or any other source, not only from disk

• return TFSEntity from generate instead of accepting out parameter

  • supports for any output format, not only writing to disk

• remove pathToPrettierConfig

  • prettier should be a part of typescript language done in #51

• remove fileReader

  • "files" are one of many possible sources and should be handled outside of the lib done in #51

Abstract from Observable in APIClient

• research possibility of abstracting Observable out to some generic Monad
• take a look at final tagless

Unable to use custom serializer

Main generate function now asks for serialize function but doesn't use it. Instead, it directly exports typescript serializer from ./src/language/typescript.ts.

index.ts should not reference any specific serializer.

Refactor swagger schema

• remove T from types and replace them with interfaces (gcanti/fp-ts#953 (comment))
• split into files under separate directory
• make all interface fields readonly

Basic support for Sketch File Format 121

• basic support for parsing/serialized https://github.com/sketch-hq/sketch-file-format (just document.json for now with all content)
• *.sketch parser for json-schema-ref-parser

Support foreign references in parameters directly

parameters:
  - name: times
    in: query
    schema:
      $ref: './shared.yaml#/components/times'

Current implementation assumes that there will be a separate run of generation for referenced entities in foreign spec. However such generation is only run for local references in local components section.

Support `file` types

OpenAPI 3.0:

• Requests:
  • single file uploads
  • upload as part of a multipart request
  • file array in a multipart request
• Responses:
  • single application/octet-stream or text/plain file - done in #129
  • other types such as application/pdf or text/xml
  • embedded files (type: string + format: byte)

Use swagger-parser

i believe we don't have to parse and validate specs by ourself. there is a https://github.com/APIDevTools/swagger-parser that can do it better.
what do you think?
@mankdev @raveclassic @sutarmin

Full support for $ref referencing for typescript-2

codegen should fully support openapi referencing even across files
see swagger-codegen java implementation for reference

Support passing headers to request calls

it's impossible to pass headers to generated request function

Add support for Chameleon schema source

Add:

• resolver
• parser
• typescript-language serializer (no need for css since css-custom-properties can be inlined in body :root

/cc @sutarmin

ResponseValidationError considered to be unsafe?

After getting some run-time exceptions in one app i took a closer look at ResponseValidationError implementation. Things that wonders me:

1. why you're setting prototype of ResponseValidationError class to itself via setPrototypeOf? Isn't it's better to use Symbol.hasInstance for hooking instanceof?
2. ResponseValidationError isn't safe because it's cannot be safely stringifed. Is this intended?

For example following code would produce run-time exceptions:

const failedValidation = pipe(
  fromEither(SomeCoded.decode(someInvalidData)),
  mapLeft<Errors, Error>(ResponseValidationError.create),
);
<RenderRemoteData data={failedValidation} ... />

where RenderRemoteData is something like

interface RenderRemoteDataProps<L, A> {
  data: RemoteData<L, A>;
  failure?: (e: L) => ReactNode;
  ...blah-blah-blah
}

const failureDefault = (e: Error) => (<div>{e.name}: {e.message}</div>);

const Component = <L, A>({
  data,
  failure = flow(toError, /* <-- downcasting ResponseValidationError to Error would cause exception like Uncaught TypeError: Function.prototype.toString requires that 'this' be a Function */ failureDefault),
}: RenderRemoteDataProps<L, A>) => {
  const error = useMemo(() => (e: L) => {
    console.warn('[RemoteDataFailure]', e);
    return failure(e);
  }, [failure]);

  return (
    {isFailure(data) && error(data.error)}
    <Blah />
  );
}

Would like to hear any thoughts on this.

Support "any" swagger type (empty curly braces)

According to spec, {} is a valid type means "any". I suggest having unknown typescript type in the generated code for this. @raveclassic @scink suggestions, objections?

Full support for enums

https://tools.ietf.org/html/draft-wright-json-schema-validation-00#section-5.20

Void response missing if there are response codes with non-void schema

When an operation defines multiple response codes including void responses (no body), the generated code does not handle void responses.

Example:

responses:
  204:
    description: Successful operation
  400:
    description: Request malformed
  404:
    description: Product not found
    schema: { $ref: "#/definitions/InstrumentOperationReject" }
  422:
    description: Product deletion failed
    schema: { $ref: "#/definitions/InstrumentOperationReject" }

Generated code (fragment):

e.httpClient.chain(
	e.httpClient.request({ /* ... */ })
	pipe(
		InstrumentOperationRejectIO.decode(value),	// undefined shall not pass
		either.mapLeft(ResponseValidationError.create),
		// ...
	)
)

test-api.yml.zip
test-api.zip

OpenApi string field with format date has bad path in generated typescript

There is an error on the path generated :

import { DateFromISODateStringIO } from '../utils/utils';

And it should be :

import { DateFromISODateStringIO } from '../../utils/utils';

readOnly writeOnly support

parameters in paths support

there can be a block parameters in paths, we need to support it

swagger-codegen-ts doesn't work with latest fp-ts and io-ts

swagger-codegen-ts have the following dependencies in package.json:

 "fp-ts": "^1.10.0",
 "io-ts": "^1.2.1",

Currently, when installed through npm it pulls up following versions:

 "fp-ts": "1.13.0",
 "io-ts": "1.8.1",

The problem is that with these versions of fp-ts and io-ts it doesn't work. It fails to generate code given valid spec file with huge and uninformative log.
As a hotfix, I'll lock minor versions of deps using ~ instead of ^.

To be done:

• 1. Research and fix problems with newer versions
• 2. Decide whether we will continue using ~ and upading versions manually or switch back to ^ when problem is resolved.

Use Nullable instead of Option

Update `from: Ref` tracking mechanism

Current implementation ties inner schema structure (paths, definitions, components etc.) to output directories so that we cannot use different names and directory structure.
We should split schema and fs cursors: from: Ref should track position in schema structure (e.g. #/components/schemas/Model and path: string - current file/directory in fs.

CLI wrapper

Do you want to be able to use this instrument as a command line tool?

allOf support

Async Api parameters do not work

using parameters do not generate arguments for a channel

Controllers are generated with unused variable

After starting generate I receive an error in generated controllers.
The error is

generate function is same as test1 in tests

Libs:

"fp-ts": "^2.4.4",
"io-ts": "^2.0.1",
"io-ts-reporters": "^1.0.0",
"io-ts-types": "^0.5.2",
"@devexperts/swagger-codegen-ts": "^2.0.0-alpha.17",
"@devexperts/utils": "^1.0.0-alpha.11",

System: win10

Also, I checked tests here and got the same result.

STR:

• clone project
• yarn install
• yarn test:run

Support for ServerObject and ServerVariableObject

• we should support flexible server path configuration:
  • https://swagger.io/docs/specification/api-host-and-base-path/
  • https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#server-object-example
  • https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#server-variable-object

Move to Yarn

We have yarn as the de facto standard for our projects, but this one doesn't contain yarn lock file. Is it for purpose or what? @raveclassic @scink

Support AsyncAPI (websockets)

Following OAI/OpenAPI-Specification#523 (comment) there's a spec for describing schemas based on websocket communication: https://www.asyncapi.com/

We need to research possibility of adding a codec and a language for it.

Setup monorepo with lerna

As the codebase grows, new languages and specs are added, to better control tests and builds we need to turn the project to monorepo and split the code into several subpackages:

• @devexperts/swagger-codegen-ts/core
• @devexperts/swagger-codegen-ts/spec/swagger-2
• @devexperts/swagger-codegen-ts/spec/openapi-3
• @devexperts/swagger-codegen-ts/languageserializer/typescript-swagger-2
• @devexperts/swagger-codegen-ts/languageserializer/typescript-openapi-3

Suggestions are welcome.

/cc @sutarmin @scink

Support enums with single value

Now enum with single value leads to error during typescript compilation, because enum generates as io-ts union type, witch should have at least two elements.

According spec it it valid case https://tools.ietf.org/id/draft-fge-json-schema-validation-00.html#rfc.section.5.5.1

The value of this keyword MUST be an array. This array MUST have at least one element. Elements in the array MUST be unique.

No parameters on tag do not create parameters if there are parameters on group of tags

generate fails on properties with kebab case

if specification contains properties in kebab generate fails

multifile and crossfile references

there are cases when you have several spec files. it causes need to proceed several files in one go. and there might be references to other files. we need to support such cases

YAML support

how about use x-name or something for generated name?

how about use x-name or something for generated name?

Support for Page objects

https://github.com/sketch-hq/sketch-file-format/blob/master/schema/layers/page.schema.yaml

Query string is incorrectly serialized for primitive parameters

swagger-codegen-ts/src/language/typescript/3.0/serializers/operation-object.ts

Line 212 in 409e3ad

`encodeURIComponent(compact([${c}]).join('&'))`,

incorrectly serializes result of intercalateSerializedFragmentsNEA above because it uses unsafe Array.prototype.join expecting the items to be of string type but they are Eithers.
Suggested solution:

• use join from openapi-3-utils
• sequence list of Eithers first

Full support for $ref referencing for typescript-3

AllOf with recursion

When type, built with allOf, references itself, TS raises following error:

[ts] 'FieldFilterExpressionTreeIO' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer. [7022]

We need to determine if there is such a circular reference and add recursion to the codec in such case.

Support ws bindings for asyncapi-2.0.0

OpenAPI 3.0 support

• rename swagger.ts to swagger-2.0.ts see #43
• add openapi-3.0.ts as additional parser and implement OpenAPI 3.0 spec
• support parser configuration
• add typescript language template for OpenAPI 3.0

Full support for Data Type Format

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#dataTypeFormat
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#dataTypeFormat
https://www.asyncapi.com/docs/specifications/2.0.0/#dataTypeFormat

Full support for parameters

• support parameters in PathItemObject https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#path-item-object
• support parameters in header/formData/path/body of OperationObject
• support arrays as values
• support enums in parameters

file support: #73
query parameters support: #74

Support arbitrary strings as names of entities

• current implementation doesn't process names in any way so that for names like Foo.Bar.Baz we generate interface Foo.Bar.Baz which is invalid TS
• we need to remove any invalid characters from all names when generating TS

Support oneOf for openapi-3

Full support query parameters

• query should be serialized according to specs: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#style-values
• asyncapi support is requested here: asyncapi/spec#294

Refactor typescript language template

• split into small files
• move out repeating utils

Async API: messages can not reference schemas

message generates import from messages instead of schemas directory

response with status 201 has always body type void

maybe, it's enough to add '201' to SUCCESSFUL_CODES