Skip to content

FAQ

Jump to bottom
wing328 edited this page Apr 5, 2017 · 38 revisions

Table of contents

GENERAL

How long does it take to release a stable version (e.g. 2.1.5 => 2.1.6)?

For tiny release (e.g. 2.1.5 to 2.1.6), it will take roughly 3 to 4 months.

For minor release (e.g. 2.1.6 to 2.2.0), it will take roughly 4 to 6 months, depending on the features/bug fixes included in the minor release.

For major release, it should probably take more than 6 months.

How to debug Swagger Codegen?

You can leverage the following debug flags when generating the libraries:

  • [debugSwagger] prints the swagger specification as interpreted by the codegen
  • [debugModels] prints models passed to the template engine
  • [debugOperations] prints operations passed to the template engine
  • [debugSupportingFiles] prints additional data passed to the template engine

Here is an example using debugModels:

mvn clean package
java -DdebugModels=true -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l ruby -o /var/tmp/ruby/

How do "tags" affect the generated code?

tags basically groups endpoints into the same API class file. For example, an endpoint with the "store" tags will be generated in the StoreApi class file.

Ref: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#tagObject

How to import Java objects that are not defined as model in the OpenAPI/Swagger spec?

Please refer to https://github.com/swagger-api/swagger-codegen#bringing-your-own-models

What does https://editor.swagger.io leverage Swagger Codegen for code generation?

https://editor.swagger.io submits HTTP request to https://generator.swagger.io (part of Swagger Codegen project) to generate code.

https://generator.swagger.io ususally runs the latest stable version (not latest master). To use the latest master of Swagger Codegen, you will have to clone the project and build the JAR locally. Getting Started is a good starting point.

Is there a way to disable certificate verification?

Please add -Dio.swagger.parser.util.RemoteUrl.trustAll=true when generating the code.

How to skip certain files during code generation?

For example, to skip git_push.sh, one can create a file named .swagger-codegen-ignore in the output directory and put git_push.sh in that file, which just works like .gitignore.

.swagger-codegen-ignore is auto-generated by default.

Is https://editor.swagger.io using the latest master of Swagger Codegen for code generation?

No. https://editor.swagger.io leverages https://generator.swagger.io (part of the Swagger Codegen project) to generate code and generator.swagger.io usually runs the latest stable version.

To use the latest master, you can either build the JAR locally or use docker.

git

How can I rebase my PR on the latest master?

Please refer to http://rypress.com/tutorials/git/rebasing, or follow the steps below (assuming the branch for the PR is "fix_issue_9999"):

  1. git checkout master
  2. git pull upstream master (assuming upstream is pointing to the official repo)
  3. git checkout fix_issue_9999
  4. git rebase master
  5. Resolve merge conflicts, if any, and run "git commit -a"
  6. Rebase done (you may need to add --force when doing git push)

(To setup upstream pointing to the official repo, please run git remote add upstream https://github.com/swagger-api/swagger-samples.git)

How can I update commits that are not linked to my Github account?

Please refer to https://help.github.com/articles/changing-author-info/ or you can simply add the email address in the commit as your secondary email address in your Github account.

Any useful git tips to share?

Yes, http://www.alexkras.com/19-git-tips-for-everyday-use/

How can I submit a PR to fix bugs or make enhancements?

Visit https://github.com/swagger-api/swagger-codegen and then click on the "Fork" button in the upper right corner. Then in your local machine, run the following (assuming your github ID is "your_user_id")

  1. git clone https://github.com/your_user_id/swagger-codegen.git
  2. cd swagger-codegen
  3. git checkout -b fix_issue9999
  4. make changes
  5. git commit -a (you may need to use git add filename to add new files)
  6. git push origin fix_issue9999
  7. Visit https://github.com/swagger-api/swagger-codegen in your browser and click on the button to file a new PR based on fix_issue9999

Generator Service

https://generator.swagger.io/

The API is split in to two sections: client and server. The endpoints under client are meant for generating code to consume an API. The endpoints under server are meant for generating code to run the API itself (server stubs etc).

Each section has 4 endpoints

  • Get a list of languages/frameworks that you can generate code for
  • Get options schema for a language/framework (where do these options go? options in GeneratorInput?)
  • Post GeneratorInput to generate code to a zip file and get back link to file
  • Get zip file (download)

Example node script to generate typescript angular client from swagger.yaml. Note that we use http. Request cannot verify the first certificate if using https (at the time of writing this)

var fs = require('fs');
var path = require('path');
var jsYaml = require('js-yaml');
var request = require('request');
var unzip = require('unzip2');

var codeGenEndpoint = 'http://generator.swagger.io/api/gen/clients';
var language = 'typescript-angular';

fs.readFile(path.resolve('swagger.yaml'), 'utf8', function (error, yaml) {
    if (error) {
        throw error;
    }

    var swaggerObj = jsYaml.load(yaml);

    var postBody = {
        spec: swaggerObj,
        options: {
            modelPropertyNaming: 'camelCase',
            apiPackage: 'api.clients.settings',
            modelPackage: 'api.clients.settings'
        }
    };

    request.post({
        url: codeGenEndpoint + '/' + language,
        body: JSON.stringify(postBody),
        headers: {
            'Content-Type': 'application/json'
        }
    }, function(error, response, body){
        if (error) {
            throw error;
        }

        if (response.statusCode !== 200) {
            throw new Error('Response code was not 200. ' + body)
        }

        var responseObj = JSON.parse(body);

        request({
            url: responseObj.link,
            encoding: null
        }).pipe(unzip.Extract({ path: 'src/client/js/codegen/settingsApi'}));
    });
});

Java

Using Java API client to make request results in SSL errors due to invalid certificate. Is there a way to bypass that?

Yes, please refer to http://stackoverflow.com/a/6055903/677735

Android

How can I generate an Android SDK?

The Java SDK is also compatible with Android.

[RECOMMENDED] To generate the Java SDK with okhttp and gson libraries, run the following:

mvn clean package
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l java --library=okhttp-gson \
  -D hideGenerationTimestamp=true \
  -o /var/tmp/java/okhttp-gson/

You can also generate the Java SDK with other HTTP libraries by replacing okhttp-gson with retrofit for example. For a list of support libraries, please run

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l java

To generate the Android SDK with volley, please run

mvn clean package
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l android --library=volley \
  -o /var/tmp/android/volley/

We do not recommend using the default HTTP library (Apache HttpClient) with android as it's not actively maintained.

For discussion related to method count, please refer to https://github.com/swagger-api/swagger-codegen/issues/687

C-Sharp

I got the warning CSC: warning CS2002: Source file 'Api/FakeApi.cs' specified multiple times in Xamarin. How can I resolve it?

The warning has no impact to the build process so you should be able to build the solution without issue. The warning should be addressed in the upcoming stable release of Xamarin.

Objective-C

How do I run integration test with Petstore ObjC API client?

Here are the steps:

git clone https://github.com/swagger-api/swagger-codegen.git
cd swagger-codegen/samples/client/petstore/objc/default/SwaggerClientTests
mvn integration-test

Besides default (folder) ObjC API client, there's also core-data for another ObjC API client with Core Data support.

Swift

How do I run integration test with Petstore Swift API client?

Here are the steps:

git clone https://github.com/swagger-api/swagger-codegen.git
cd swagger-codegen/samples/client/petstore/swift/default/SwaggerClientTests
mvn integration-test

Besides default (folder), there's another folder promisekit for Swift API client with PromiseKit support

git clone https://github.com/swagger-api/swagger-codegen.git
cd swagger-codegen/samples/client/petstore/swift/promisekit/SwaggerClientTests
mvn integration-test

would suggest when compiling to use flag to ignore tests. The tests requires extra dependencies and the compilation might fail due to that.

Navigation

Codegen Usage

Clone this wiki locally