forked from loafle/openapi-generator-original
136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
## Migration guide: from Swagger Codegen to OpenAPI Generator
|
|
|
|
OpenAPI Generator is a fork of `swagger-codegen` between version `2.3.1` and `2.4.0`.
|
|
This community-driven version called "OpenAPI Generator" provides similar functionalities and can be used as drop-in replacement.
|
|
This guide explains the major differences in order to help you with the migration.
|
|
|
|
### New maven coordinates
|
|
|
|
You can find our released artefact on maven central:
|
|
|
|
**Core:**
|
|
|
|
Old:
|
|
|
|
```
|
|
<dependency>
|
|
<groupId>io.swagger</groupId>
|
|
<artifactId>swagger-codegen</artifactId>
|
|
</dependency>
|
|
```
|
|
|
|
New:
|
|
|
|
```
|
|
<dependency>
|
|
<groupId>org.openapitools</groupId>
|
|
<artifactId>openapi-generator</artifactId>
|
|
</dependency>
|
|
```
|
|
|
|
**Cli:**
|
|
|
|
```
|
|
<dependency>
|
|
<groupId>io.swagger</groupId>
|
|
<artifactId>swagger-codegen-cli</artifactId>
|
|
</dependency>
|
|
```
|
|
|
|
New:
|
|
|
|
```
|
|
<dependency>
|
|
<groupId>org.openapitools</groupId>
|
|
<artifactId>openapi-generator-cli</artifactId>
|
|
</dependency>
|
|
```
|
|
|
|
**Maven plugin:**
|
|
|
|
```
|
|
<dependency>
|
|
<groupId>io.swagger</groupId>
|
|
<artifactId>swagger-codegen-maven-plugin</artifactId>
|
|
</dependency>
|
|
```
|
|
|
|
New:
|
|
|
|
```
|
|
<dependency>
|
|
<groupId>org.openapitools</groupId>
|
|
<artifactId>openapi-generator-maven-plugin</artifactId>
|
|
</dependency>
|
|
```
|
|
|
|
|
|
### New generators names
|
|
|
|
When you run OpenAPI Generator, you need to select a target language (`-l` option in the cli).
|
|
All languages of `swagger-codegen` have been migrated to `openapi-generator`, but some names were changed, in order to be more consistent.
|
|
|
|
| name in `swagger-codegen` | name in `openapi-generator` |
|
|
|--|--|
|
|
| `akka-scala` | `scala-akka` |
|
|
| `scala` | `scala-httpclient` |
|
|
| `jaxrs` | `jaxrs-jersey` |
|
|
| `qt5cpp` | `cpp-qt5` |
|
|
| `cpprest` | `cpp-restsdk` |
|
|
| `tizen` | `cpp-tizen` |
|
|
| `sinatra` | `ruby-sinatra` |
|
|
| `swift` | `swift2-deprecated` |
|
|
| `lumen` | `php-lumen` |
|
|
| `slim` | `php-slim` |
|
|
| `ze-ph` | `php-ze-ph` |
|
|
| `nancyfx` | `csharp-nancyfx` |
|
|
|
|
|
|
### New parameters name
|
|
|
|
Some parameters were renamed.
|
|
Often you need to replace "Swagger", with "OpenAPI".
|
|
Some examples:
|
|
|
|
| name in `swagger-codegen` | name in `openapi-generator` |
|
|
|--|--|
|
|
| `debugSwagger` | `debugOpenAPI` |
|
|
| `GenerateSwaggerMetadata` | `GenerateOpenAPIMetadata` |
|
|
| `swagger.codegen.undertow.apipackage` | `openapi.codegen.undertow.apipackage` |
|
|
| `swagger.codegen.undertow.modelpackage` | `openapi.codegen.undertow.modelpackage` |
|
|
|
|
|
|
### Ignore file
|
|
|
|
`.swagger-codegen-ignore` is replaced by `.openapi-generator-ignore`.
|
|
The syntax inside the file stays the same.
|
|
|
|
You don't need to rename the file manually, OpenAPI Generator will do it when your run it against an existing an existing output directory.
|
|
(When there is no `.openapi-generator-ignore` in a folder, if a `.swagger-codegen-ignore` file is present it will be considered and renamed to `.openapi-generator-ignore`).
|
|
|
|
|
|
### Metadata folder
|
|
|
|
The metatata folder (to store the `VERSION` file for example) is now called `.openapi-generator/` instead of `.swagger-codegen/`.
|
|
|
|
|
|
|
|
### New default values for the generated code
|
|
|
|
If you use a generator without specifying each parameter, you might see some differences in the generated code.
|
|
As example the default package name used in the generated code has changed.
|
|
You need to have a look at the specific value, depending of your target language, but often `Swagger` îs replaced by `OpenAPITools` and `io.swagger` is replaced by `org.openapitools`.
|
|
Concretely if you did not specify anything when you are generating java code, a file `org/openapitools/api/PetApi.java` might be generated instead of `io/swagger/api/PetApi.java`.
|
|
|
|
If this is a problem for you, you need to explicitly set the the parameter value in order to match with the `swagger-codgen` default value (`apiPackage` == `io.swagger` in the previous example with the java generator).
|
|
|
|
|
|
### New fully qualified name for the classes
|
|
|
|
If you have extended some generators in your project, and you are looking for a specific class, replace the `io.swagger.codegen` package (old name) with `org.openapitools.codegen` package (new name).
|
|
|
|
Example: `org.openapitools.codegen.DefaultGenerator`
|
|
|
|
|
|
[Back to OpenAPI-Generator's README page](../README.md)
|