Skip to content
GitLab

FAQ · Changes

Page history
Initial Wiki authored by Jeremie Bresson's avatar Jeremie Bresson
Hide whitespace changes
Inline Side-by-side
FAQ.md 0 → 100644
View page @ 016d8b1b
# Table of contents
- [General](#general)
- [git](#git)
- [Generator Service](#generator-service)
- [Java](#java)
- [Android](#android)
- [C#](#c-sharp)
- [Objective-C](#objective-c)
- [Swift](#swift)
- [TypeScript](#typescript)
## GENERAL
### 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), it will take roughly 3 to 4 months.
For minor release (e.g. 3.1.6 to 3.2.0), it will take roughly 4 to 6 months, depending on the features/bug fixes included in the minor release.
For major releases, it should probably take more than 6 months.
### How to debug OpenAPI Generator?
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/openapi-generator-cli/target/openapi-generator-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/openapitools/openapi-generator#bringing-your-own-models
<!--
### What does https://editor.swagger.io leverage OpenAPI Generator for code generation?
https://editor.swagger.io submits HTTP request to https://generator.swagger.io (part of OpenAPI Generator project) to generate code.
https://generator.swagger.io usually runs the latest [stable version](https://github.com/openapitools/openapi-generator/releases/latest) (not latest master). To use the latest master of OpenAPI Generator, you will have to clone the project and [build the JAR locally](https://github.com/openapitools/openapi-generator#getting-started) or use [docker](https://github.com/openapitools/openapi-generator#public-pre-built-docker-images).
-->
### 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 `.openapi-generator-ignore` in the output directory and put `git_push.sh` in that file, which just works like [.gitignore](https://git-scm.com/docs/gitignore).
[.openapi-generator-ignore](https://github.com/openapitools/openapi-generator/blob/master/samples/client/petstore/php/.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 swagger-codegen
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
-l 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)
3.
## 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/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/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/openapitools/openapi-generator 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 into 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)
```javascript
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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-cli.jar config-help -l java
```
To generate the Android SDK with [`volley`](https://github.com/mcxiaoke/android-volley), please run
```
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-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.
## 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/openapitools/openapi-generator.git
cd openapi-generator/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](https://en.wikipedia.org/wiki/Core_Data).
## 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/SwaggerClientTests
mvn integration-test
```
Besides `default` (folder), there's another folder `promisekit` for Swift API client with [PromiseKit support](https://github.com/mxcl/PromiseKit)
```
git clone https://github.com/openapitools/openapi-generator.git
cd openapi-generator/samples/client/petstore/swift/promisekit/SwaggerClientTests
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.
Ref: https://github.com/swagger-api/swagger-codegen/issues/4098#issuecomment-328142793
## 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)
```