swagger-ts-client

Swagger-ts-client is a tool that generate TypeScript types and http client from Swagger (open api). The code generation is highly configurable through a configuration file. Refer Configuration section for more details.

The generated code can completely controlled by using Handlebar templates.Refer template section for more section. The default template generates http clients based on the SuperAgent library.

Swagger-ts-client can import swagger definition from multiple sources using provider plugins.The default provider imports JSON formated swagger definition file from the file system.There is also an Http provider built in, that can be configured to import swagger from a url.

Some differences form other tools for the same purpose

provides a lot of control in code generation.
template based code generation. Does not tye the generated code into come specific http client library.
full support for Generics. Infers generis from swagger types definition especially when used with Swashbuckle, C# and .net.
can be configured to generate Interface or Classes
can import swagger definition from multiple sources using providers.Built in providers includes File system And Http providers.

Whats new

Added option to register custom HandleBars helpers vis settings.

Getting Started

Swagger-ts-client is written in typescript nad runs on NodeJS and is packed with NPM . You need NodeJS installed to install and run Swagger-ts-client.

Installing

swagger-ts-client and be installed globally locally as a dev dependency.

npm

$ npm install swagger-ts-client --save-dev

Generating Code

when run with out any arguments , swagger-ts-client looks for a config file named ts-client.config.js and loads configuration from it.

$ swagger-ts-client

A minimal all defaults no config file example.Loads swagger from swagger.json generates types to ./generatedTypes/fooApiTypes.ts and generates Http Clients to ./httpProxy/

$ swagger-ts-client -s ./swagger.json -t ./generatedTypes/fooApiTypes.ts -o ./httpProxy/

All generated types are generated into a single file. Operations, default are grouped by tag(swagger spec) and for each group a class is generated and written into separate files.

Configuration

swagger-ts-client looks for a config file named ts-client.config.js and loads settings from it. Some configuration can be overridden by comment line args.

Configuration file

The configuration file needs to export a configuration object. The configuration object has the following schema.

{
    swaggerFile?: string;
    swaggerProvider?: {
        provide:Function
    };
    templateHelpers?:{
        [index: string]:IHandleBarHelper
    };
    type?: {
        typeAliases?: { 
            [index: string]:string
        };
        generatedTypes?: "type"|"interface"|"class";
        membersOptional?: boolean;
        templateFile?: string;
        outPutPath?: string;
        templateTag?: any;
    };
    operations?: {
        operationsGroupNameTransformFn?: Function;
        operationsNameTransformFn?: Function;
        ungroupedOperationsName?: string;
        templateFile?: string;
        outPutPath?: string;
        outFileNameTransformFn?: Function;
        templateTag?: any;
    };
}

For example; a simple config file.

const settings ={
    swaggerFile:"../swagger.json",
    type:{
        outPutPath:"./src/models.ts"
    },
    operations:{       
        outPutPath:"./src/httpClient/"
    }
};
module.exports=settings;

Configuration Options

swaggerFile

The file to import Swagger definitions from. Expects to be JSON representation of swagger. YML is currently not supported.

swaggerProvider

An instance of a swagger provider plugin to be used when swagger is not imported from file.

Example

  const settings ={ 
      swaggerProvider:new HttpSwaggerProvider("http://api.mysite.com/swagger","Username01","passw0rd")
  }

  module.exports=settings;

templateHelpers

A hash of functions with that are registered with the handlebar runtime as handlebar helper.

Example

  templateHelpers : {
      toUpper: function(context,...options) {
          if (context && typeof(context) === "string"){
              return context.toUpperCase();
          }
          else{
               return ""
          }
         
      },
      toLower: function(context,...options) {
          if (context && typeof(context) === "string"){
              return context.toLowerCase();
          }
          else{
               return ""
          }
         
      }
  }

type

All configuration for Type generation.

type.typeAliases

A hash of strings aliases that provide alternative names for existing types.

Example

  const settings ={ 
      type:{
          typeAliases:{
              "Int32":"number"
          }
      }
  }

  module.exports=settings;

type.generatedTypes Instructs the generator to generate either class or interface . values can be "class" or "interface". Default is "class"
type.membersOptional

A flag if true generates all members of generated types are optional .Default is true
type.templateFile

Path to a Handlebar template file used to generate Types . Refer Template section
type.outPutPath

Path to write the the generated types file to. If the directory does not exist, it will be created. Default is "./serverTypes/serverTypes.ts"
type.templateTag

This can be any object and it will be made available in the template.
operations

All configuration for Operations generation.
operations.operationsGroupNameTransformFn A Function when called with an operation schema, should return name of the group group that the operation should belong to. This name will be used as name of the generated class in which the the operation would me a method.

default is concatenation of Tag and "HttpSvc".

The signature of the function is as follows.
```
(operationName: string, httpVerb: HttpVerb , operation: Swagger.Operation) => string;
```
HttpVerb can be any of the following "get"|"put"|"post"|"delete"|" options"|"head"|" patch"
operations.operationsNameTransformFn

A Function when called with an operation schema, should return name of the operation should belong to. This name will be used as name of the method which would perform the http operation.

Default is , if the schema has tag and that tag is present in the operation ID , it will be replaced with the verb. Example

The signature of the function is as follows.
```
(operationName: string, httpVerb: HttpVerb , operation: Swagger.Operation) => string;
```
HttpVerb can be any of the following "get"|"put"|"post"|"delete"|" options"|"head"|" patch"
operations.ungroupedOperationsName

A string that will ne sued as the name of all un named operations
operations.templateFile

Path to Handlebar template to be used for code generation. The default template generates Classes for each operation group using Superagent.
operations.outPutPath

Path to write the the generated types file to. If the directory does not exist, it will be created. A file will be created for each operation group. Default is "./serverTypes/httpClients/
operations.outFileNameTransformFn

A Function when called with an operation group, should return name of file to which the operation group would be written into

Default is a function that returns operationGroup.ts

CLI

Executing swagger-ts-client with out any options, it tries to load settings from ./ts-client.config.js. and generate code.

The recommended way of using swagger-ts-client is by putting all the configuration in the config file, but some options are provided which will the configuration settings from the config file. Using these options it might be possible to run swagger-ts-client with out a config file.

There are some options that can be used to change

Option		Explanation
-V	--version	output the version number
-c	--config ./path/to/config.file.js	use the configuration file from the path
-s	--swaggerFile ./path/to/swagger.doc.json	use swagger definition from the path
-t	--typesOut ./path/to/generate/types.ts>	generate output types at the location
-u	--url http://url.to.swaggerDef/swagger/v1/docs	use url as swagger source
-o	--operationsOut ./path/to/generate/operations/	generate operations at the location
-h	--help	output usage information

Template

Providers

Build

Clone or download from git hub.

yarn
yarn build

cjam/swagger-ts-client

swagger-ts-client

Some differences form other tools for the same purpose

Whats new

Getting Started

Installing

Generating Code

Configuration

Configuration file

Configuration Options

CLI

Template

Providers

Build