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

[feat][docs][website] Initial docusaurus based site (#1770)

Browse Source 
* Iniital docusaurus based site

* Remove error about default local being used by String.format

* Change pinned users to represent global presence rather than alphabetical order pinning

* Include generator indexes in ensure-up-to-date (docusaurus site and /generators/README)

* Add Font Awesome attribution footer

* Remove feature callout until it is completed

* Include NPM try it out section

* Improve "Getting Started" type docs

* Include new custom template documentation

* Updating templating and customization docs

* Add vendor extension docs

* Cleanup templating page(s).

* Move users to yaml file for easy edit.

* travis configuration, and baseUrl mods to image URLs

* [docs] Migrate FAQ, release summary  from wiki

FAQ has been split into multiple smaller documents to better categorize
and allow users to find what they're looking for (in docs folder or in
new website).

Release summary information (versioning strategy and cadence) has been
migrated from the Wiki and clarified a bit.

Also adds copy button for all code snippets in website.

* Copy current contributing/code of conduct to website

* [docs] Creating a new generator
This commit is contained in:
Jim Schubert
2019-01-18 04:39:33 -05:00
committed by William Cheng
parent 9cba9b6f88
commit 6fe9a52229
197 changed files with 13420 additions and 5211 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/migration-from-swagger-codegen.md
View File

@@ -1,4 +1,7 @@
## Migration guide: from Swagger Codegen to OpenAPI Generator
---
id: swagger-codegen-migration
title: Migrating from Swagger Codegen
---
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.
@@ -20,13 +23,13 @@ This guide explains the major differences in order to help you with the migratio
- [Body parameter name](#body-parameter-name)
- [Generators not yet fully migrated](#generators-not-yet-fully-migrated)
### New docker images
## New docker images
The docker images are available on DockerHub: https://hub.docker.com/u/openapitools/
**CLI for OpenAPI Generator**
Image to run OpenAPI Generator in the command line (see [OpenAPI Generator CLI Docker Image](../README.md#openapi-generator-cli-docker-image))
Image to run OpenAPI Generator in the command line (see [OpenAPI Generator CLI Docker Image](https://github.com/OpenAPITools/openapi-generator/blob/master/README.md#openapi-generator-cli-docker-image))
Old: `swaggerapi/swagger-codegen-cli`
@@ -34,14 +37,14 @@ New: `openapitools/openapi-generator-cli`
**OpenAPI Generator as web service**
Image to run OpenAPI Generator as a web service (see [OpenAPI Generator Online Docker Image](../README.md#openapi-generator-online-docker-image))
Image to run OpenAPI Generator as a web service (see [OpenAPI Generator Online Docker Image](https://github.com/OpenAPITools/openapi-generator/blob/master/README.md#openapi-generator-online-docker-image))
Old: `swaggerapi/swagger-generator`
New: `openapitools/openapi-generator-online`
### New maven coordinates
## New maven coordinates
You can find our released artefact on maven central:
@@ -101,14 +104,14 @@ New:
</dependency>
```
### Changes in Maven Plugin
## Changes in Maven Plugin
OpenAPI Generator 3.0.0 has introduced `<generatorName>` and deprecated `<language>`, because this refers to generator names which embed more than just "language".
If both options are present, you'll be presented with an error. If only `<language>` is provided, you'll be presented instructions for updating to the new config.
### New generators names
## New generators names
When you run OpenAPI Generator, you need to select a target generator (`-g` 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.
@@ -130,7 +133,7 @@ All languages of `swagger-codegen` have been migrated to `openapi-generator`, bu
We provide a temporary mapping in code for these old values. You'll receive a warning with instructions to migrate to the new names.
### New parameters name
## New parameters name
Some parameters were renamed.
Often you need to replace "Swagger", with "OpenAPI".
@@ -144,14 +147,14 @@ Some examples:
| `swagger.codegen.undertow.modelpackage` | `openapi.codegen.undertow.modelpackage` |
### Renamed Mustache Template Variables
## Renamed Mustache Template Variables
The template variable `{{datatype}}` was renamed to `{{dataType}}` for consistency reason.
Corresponding java code: `CodegenProperty.datatype` is renamed to `CodegenProperty.dataType`.
(If you're **not** using customized templates with the `-t` option, you can ignore the mustache variable renaming above.)
### Ignore file
## Ignore file
`.swagger-codegen-ignore` is replaced by `.openapi-generator-ignore`.
The syntax inside the file stays the same.
@@ -160,13 +163,13 @@ You don't need to rename the file manually, OpenAPI Generator will do it when yo
(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
## 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
## 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.
@@ -176,13 +179,13 @@ Concretely if you did not specify anything when you are generating java code, a
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
## 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`
### Body parameter name
## Body parameter name
In OpenAPI spec v3, there's no body parameter, which is replaced by [Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#request-body-object). The parameter name for Request Body is named automatically based on the model name (e.g. User). To control how the "Request Body" parameter is named, please add the vendor extension `x-codegen-request-body-name` to the operation:
@@ -241,16 +244,3 @@ paths:
- 'read:pets'
```
If your API client is using named parameters in the function call (e.g. Perl required & optional parameters, Ruby optional parameters), you will need to add `x-codegen-request-body-name` to the spec to restore the original body parameter name.
# Generators not yet fully migrated
The following gnereators are not yet fully migrated and tested
- ~~rust-server~~ (migrated)
- ~~`apex`~~ (migrated)
and we welcome contributions from the community to help with the migration.
UPDATE: all generators have been successfullly migrated.
[Back to OpenAPI-Generator's README page](../README.md)