Notice

This is a forked project of swagger-ts-client by Jayasanker Karakulath, with the following modifications:

• add support for inline types
• interfaces are prefixed with I
• add baseUrl with default
• Change Service Name to pascal casing
• add operations name filter so it will always be a valid function name
• add rendering of info section
• add handling of parent properties
• add anonymous parameters
• add function parameter camel casing
• add handlebars helpers for eq, ne, lt, gt, lte, gte, and, or
• add yaml support
• add array support
• add jsdoc comments to generated code
• add sample generation (as a crude testing tool), no validations.
• add support for ibm endpoint
• add definition ref
• add word-wrap to template
• add header support
• add cli parameter for setting the ungrouped APIs
• support streams for binary responses
• support type aliases for primitives

NOTE: This is a toy project - use as your own risk!

Alternatives

While I worked on fixing some issues with this project, I've also checked out a few alternatives which work better, I've decided not to scrap the modifications but rather offer them with a list of alternatives:

• autorest - a project from microsoft, specifically there is autorest-typescript
• Swagger Generator and Swagger Editor

Addendum to alternatives

I've continued working on this project after I've encountered the below problems with above alternatives. I apologize in advance for not having the time to handle requests and bugs, therefore the issue tracker will stay disabled.

• Swagger Generator has some issues with OpenAPI v2 with referenced headers
• autorest is having problems with methods lacking OperationId

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 | | -g | --ungroupedName Operations | sets default for ungrouped functions | | -h | --help | output usage information |

Template

Providers

TODO

[ ] Implement allOf (petstore-expanded.v2.json)

[ ] Unit Testing

Build

Clone or download from git hub.

yarn
yarn build