jlengrand/openapi-generator
1
0
Fork 0
mirror of https://github.com/jlengrand/openapi-generator.git synced 2026-03-10 08:31:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Migration from swagger-codegen guide (#408)

Browse Source 
* Add Migration guide

* Update migration-from-swagger-codegen.md
This commit is contained in:
Jérémie Bresson
2018-05-10 07:51:19 +02:00
committed by William Cheng
parent d958480fea
commit dc4d6e499c
1 changed files with 128 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
docs/migration-from-swagger-codegen.md Normal file
View File

@@ -0,0 +1,128 @@
## 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` |
| `swift` | `swift2-deprecated` |
### 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)