Skip to content

FAQ

Jump to bottom Edit New page
William Cheng edited this page Aug 2, 2019 · 38 revisions

Table of contents

GENERAL

Is there a chat room to discuss OpenAPI Generator?

Yes, please join our Slack workspace and here is the code of conduct covering this project including the chat room.

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

For tiny release (e.g. 3.0.5 to 3.0.6), we plan to do it on a weekly basis.

For minor release (e.g. 3.1.6 to 3.2.0), we plan to do it on a monthly basis.

For major releases (e.g. 3.3.6 to 4.0.0), we plan to do it on a quarterly basis.

Does OpenAPI Generator support all new features in OpenAPI Specification v3?

No, we do not support all new features (e.g. callback, anyOf, etc) at the moment. We would definitely welcome contributions from the community to add support for these new features. Please search the issue tracker to see if anyone has opened a ticket to track the new feature. If no ticket has been opened yet, please open a new one and ideally a sample spec so that we can prioritize the feature request accordingly.

How to debug OpenAPI Generator?

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

  • [debugOpenAPI] prints the OpenAPI 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/openapi-generator-cli/target/openapi-generator-cli.jar generate \
  -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.json \
  -g 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 a model in the OpenAPI v2 or v3 spec?

Please refer to the "Bringing your own models" in the "Customization" guide

Is there a way to disable certificate verification?

Please add -Dio.swagger.parser.util.RemoteUrl.trustAll=true -Dio.swagger.v3.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 .openapi-generator-ignore in the output directory and put git_push.sh in that file, which just works like .gitignore.

.openapi-generator-ignore is auto-generated by default.

How can I customize the template to add header/footer to the auto-generated code?

You can use the -t option with the customized templates. Here is an example adding header/footer to Ruby templates.

  1. git clone https://github.com/openapitools/openapi-generator
  2. cd openapi-generator
  3. mvn clean package
  4. cp -R modules/openapi-generator/src/main/resources/ruby /var/tmp/ ## copy all Ruby templates to /var/tmp/. You can also selectively copy only the templates (e.g. api.mustache) you want to customize
  5. Edit /var/tmp/ruby/api.mustache to add the footer/header
  6. Run the following command to generate the Ruby API client with customized templates:
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
  -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
  -t /var/tmp/ruby
  -g ruby -o /var/tmp/ruby_api_client/

What are some of the use cases of the server generators (e.g. Java Spring, C# NancyFx)?

Besides generating the server code as a starting point to implement the API backend, here are some use cases of the server generators:

  1. prototyping - one can generate the server code and have a functional API backend very quickly to try different things or features.
  2. mocking - easily provide an API backend for mocking based on the examples field defined in the response object.
  3. migration - let's say one wants to migrate an API backend from Ruby on Rails to Java Spring. The server generator can save a lot of time in implementing and verify each endpoint in the new API backend.

I just submitted a PR but the CI (continuous integration) tests failed. Do you know what's wrong?

Please do the following:

  1. Click on the failed tests and check the log to see what's causing the errors.
  2. If it's related to connection timeout in downloading dependencies, please restart the CI jobs (which can be done by closing and reopening the PR)

I ran the test locally and got errors (HTTP status code: 500) from the public Petstore server. Is there a way to run the Petstore server locally for testing?

Yes, please run the following commands (assuming you've docker installed):

docker pull swaggerapi/petstore
docker run -d -e SWAGGER_HOST=http://petstore.swagger.io -e SWAGGER_BASE_PATH=/v2 -p 80:8080 swaggerapi/petstore
docker ps -a

Then add the following to your local host table:

127.0.0.1    petstore.swagger.io

I've discovered a security vulnerability with OpenAPI Generator. Who should I report the issue to?

Please contact team@openapitools.org with the details and we'll follow up with you.

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/openapitools/openapi-generator.git)

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

Please refer to https://stackoverflow.com/questions/3042437/how-to-change-the-commit-author-for-one-specific-commit 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/openapitools/openapi-generator 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/openapi-generator.git
  2. cd openapi-generator
  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/openapitools/openapi-generator in your browser and click on the button to file a new PR based on fix_issue9999

How can I submit a PR for a branch (e.g. 4.2.x)?

Visit https://github.com/openapitools/openapi-generator 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/openapi-generator.git
  2. cd openapi-generator
  3. git remote add upstream https://github.com/openapitools/openapi-generator
  4. git checkout 4.2.x
  5. git pull usptream 4.2.x (ensure it has the latest change)
  6. git log (review the latest change to this branch)
  7. git checkout -b 4.2.x-enhance (create a new branch instead of modifying 4.2.x directly)
  8. make changes
  9. git commit -a (you may need to use git add filename to add new files)
  10. git push origin 4.2.x-enhance
  11. Visit https://github.com/openapitools/openapi-generator in your browser and click on the button to file a new PR based on 4.2.x-enhance. Make sure the PR is filed against "4.2.x" branch instead of master.
  12. After the branch is merged, repeat step 3 & 4

Java

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

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

I want to use customized templates for Java Feign client. How can I do that?

You will need to provide customized files in Java/libraries/feign under the resources folder and pass the location via the -t option.

In your Gradle build script, please add the following (example):

config.templateDir = 'src/openapi-generator-templates/Java/libraries/feign

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/openapi-generator-cli/target/openapi-generator-cli.jar generate \
  -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.json \
  -g 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/openapi-generator-cli/target/openapi-generator-cli.jar config-help -g java

To generate the Android SDK with volley, please run

mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
  -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.json \
  -g 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.

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 on 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/openapitools/openapi-generator.git
cd openapi-generator/samples/client/petstore/objc/default/OpenAPIClientTests
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/openapitools/openapi-generator.git
cd openapi-generator/samples/client/petstore/swift/default/OpenAPIClientTests
mvn integration-test

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

git clone https://github.com/openapitools/openapi-generator.git
cd openapi-generator/samples/client/petstore/swift/promisekit/OpenAPIClientTests
mvn integration-test

Is Swift (2.x) generator still actively maintained?

No, please use swift3 or swift4 generator instead as we want to focus on Swift 3.x, 4.x.

TypeScript

The JSON response failed to deserialize properly into the object due to change in variable naming (snake_case to camelCase). Is there any way to keep the original naming?

Yes, please use the following option when generating TypeScript clients:

	modelPropertyNaming
	    Naming convention for the property: 'camelCase', 'PascalCase', 'snake_case' and 'original', which keeps the original name (Default: camelCase)
Add a custom footer
Add a custom sidebar
Clone this wiki locally