geeklearningio/gl-swagger-generator

Jane - An OpenAPI Specification (formerly Swagger) Client Generator

Jane - An OpenAPI Specification (formerly Swagger) Client Generator

Jane is an OpenAPI Specification client generator. It uses templates written in Handlebars to generate a client code base in various languages.

The initial release is focused on providing a strong support of C# .NET Standard 1.3 and TypeScript.

Basic usage

To generate the API client, you need to give it two things:

• The swagger json file of your API, defining all the available methods.
• A configuration json file, specifying some options for your client generation.

A configuration file looks like this:

{
  "language": "typescript",
  "framework": "angular",
  "version": "1.5",
  "mode": "singleFile",
  "dependencies": {
  },
  "mediaTypesPriorities": {
    "application/json": 1
  },
  "ambientTypes": [
  ],
  "templateOptions": {
    "clientName": "MyAPIClient"
    "scheme": {
      "override": "https"
    },
    "generateInterface": true
  }
}

To generate your API client, just run swaggen with these options:

swaggen --outputPath ./outputpath --options ./swaggen-config.json --schema ./api-swagger.json

Languages available

You can generate the client in 2 languages for the moment. Here are the docs:

• C# .NET Standard
• TypeScript Angular 1.5

Documentation

Documentation is maintained in this repository wiki

Integration

Jane will have a CLI interface but is meant to be integrated in build pipeline such as gulp. A gulp plugin acting as a wrapper for Jane is already available. Please check the wiki for guidance.

Extensibility

One purpose of this generator is to allow you to write or customize templates if needed. Please check the wiki for more information.

The story behind this project

Read the Jane's story

gl-swagger-generator's Issues

NodeJs Typescript Template

Server side typescript template would be a great addition

Support for dereferencing json pointer

As suggested in PR geeklearningio/gulp-swagger-generator#34 we should support internal json pointers in Swagger schema.

Mocks support

Features :

• Timeout
• Status and Response provided par swagger
• Custom status and response

Handle error when a header is set with a null value

Currently, when a parameter is mapped to a header but the value is set to null, it crashes with a cryptic message.

We must return an explicit exception or drop the header

Unable to generate Dictionary property with Angular template

I have the following definition in my Swagger file:

"ClaimsSet": {
    "type": "object",
    "properties": {
        "claims": {
            "type": "object",
            "additionalProperties": {
                "type": "array",
                "items": {
                    "type": "string"
                }
            }
        }
    }
}

With the .NET generator, it is properly mapped to a Dictionary<string, string[]>, but with the Angular one, the type is not resolved.
So the generated TypeScript ends with that (and cannot be compiled):

/*ClaimsSet*/
export interface ClaimsSet  {

    /**/
    claims: ;

}

Is it related to generics' support?

[Templates] builtin transient exception handling support

Integrate Polly (csharp and javascript) to ease complex exception handling policies.

• Javascript/Typescript : https://github.com/mauricedb/polly-js
• CSharp : https://github.com/App-vNext/Polly

Documentation Website

Dotnet template : Leverage HttpClientFactory

We should introduce a .netcore template using HttpClientFactory

Typescript Enum support

See : https://github.com/basarat/conf-ndc-2017/blob/master/ts/f%20string%20enum/stringEnum.ts

Remove default content/media types

Currently, if not consumes or produces media types are specified, the generator will add "application/json". While this might come handy, it actually makes a wild assumption and hides a incomplete swagger definition.

We did this in the first place because we faced such definitions with some customer's swagger definitions.

This should be removed in favor of a guidance about how to use custom swagger visitor to fix the definition prior to generation.

[CSharp] Unsupported Media Type

Currently if the server return an unexpected media type, the client will throw a NullReferenceException. This should return something like a UnexpectedMediaTypeApiException and provide access to the body for logging and debugging purpose.

Open API 3 support

Angular 4 template : generateInterface doesn't work

If I set the generateInterface option to true in the templateOptions, the Interface file is not generated.
In the client file, I have "implements IMyService", but the interface IMyService is not generated.

Write angular 2 integration tests

Split Language packs from core library

[Csharp] Advanced Polly Support

More features could be built around polly support.

• multiple policies which selection would be done base on selectors
  • tags,
  • operation name / path fragments
  • security definitions
• automatically Wrap matched policies together based on priorities then order

Angular 1.5 template

• Re-adapt old templates
• Implement new media type behavior

DateTime Support

See ideas here : geeklearningio/gulp-swagger-generator#33

CLI - support multiple configuration at once.

Support having an array of configuration in the configuration file so we can generate different clients with just one command and one configuration file.

Enum support

Enumerations are today converted to strings

[Templates] Override version

For the project generation flavors which are likely to be published and consumed as package we should provide a way to set the version.

Add default response support

as documented here : https://swagger.io/docs/specification/2-0/describing-responses/

Write netstandard integration tests

Api method with optional parameter still generates client with mandatory parameter

Writting an api controller action like the following:

        [HttpGet("control")]
        [ProducesResponseType(typeof(Response<DataTransfer.ControlRegister.Control[]>), 200)]
        public async Task<IActionResult> ControlGetAll(bool includeParameters = false)
        {
            var rules = await this.policyService.GetAllControlsAsync(includeParameters);
            return this.Maybe<DataTransfer.ControlRegister.Control[]>(rules.Select(DataTransfer.ControlRegister.Control.From).ToArray());
        }

Should have the parameter includeParameters as optional, but the generated code still requires that parameter to get the correct response.

Angular 4 template (dev branch) : problem with version 2.x.x of ng-packagr

The package generated has a dev-dependency on ng-packagr 2.0.0. But it creates errors:

Error: Cannot find module 'tsickle/src/tsickle'

The ng-packagr changelog says the 2.x versions are for angular 5 : https://github.com/dherges/ng-packagr/blob/master/CHANGELOG.md#200-2018-02-05

Solution : set ng-packagr version to 1.7.0 to fix this (tested)

Typescript Language Pack

Todo :

• camlCaseFilters
• languageFilter (without generic support)

Nice to have (lot of work to be done)

• genericFilter

CLI - provide a way to override configuration option from the command line

Full Generics Support

Angular 2 template

• Language filter
• SDK
  • Media formatters
    • Json
    • FormData
  • Base client
    • Basic request support
    • Cancellation support
    • Polly support
• Template.json
• Typing partials : _type and _typeCore
• Definition template
• Client template

Full support for $ref and external $refs

#5 had to be reverted because it had too much side effects. Investigating the root cause of this, I think we need to postpone this as it requires a bit of design to bring a full support for this part of the specification.

Inconsistent line endings in generated file

Original issue : geeklearningio/gulp-swagger-generator#32

Hi,

I'm using gulp-swagger-generator with the template typescript-angular, and it works like expected, but the generated file has inconsistent line endings.

It seems that Unix line endings (LF) are used in the interfaces and in the client mock, while in the real client there are Windows line endings (CR LF).

Though it is not a big issue, it would be nice to fix it in a next release! :)

Thanks for the great work!

Api with Parameter of type DateTime generates parameter with type DateTimeOffset

Hi guys,

On my api method I have a parameter type of DateTime, on the generated client it changes to DateTimeOffset.

Normally that wouldn't be a problem.
However, I have a generic implementation such as

   var convertedValue = Convert.ChangeType(paramValue, parameter.ParameterType, System.Globalization.CultureInfo.InvariantCulture);
   parameterValues.Add(convertedValue);

And it throws exception because DateTimeOffset does not implement IConvertible

The type should be a developer's choice instead of being enforced by the generator.
Cheers.

Angular 1.5 template: scheme should be set via ClientConfigurationService

.net core template : Null header leads to invalid request

when a header is not provided (optional). The generated request is invalid and fails

Tests : Write integrations tests

• Typing
  • Recursive Arrays

Support $ref for parameters

204 Handling and Void Abstracted Type

void must be handled.

204 must be supported.

Csharp template will need to be fixed as Task<void> needs to be mapped to Task

[Csharp] Exception and status code support

• Use the appropriate base exception based on the status code. geeklearningio/gl-dotnet-restkit#5
• Parse the content of the request if type information is provided

Custom template support