mirror of
https://github.com/OpenAPITools/openapi-generator.git
synced 2025-05-12 12:40:53 +00:00
Update documentation (#184)
* update documentation * fix broken links * minor fix * add more section * add line break to license * add list of founding members * fix typo
This commit is contained in:
William Cheng
GitHub
parent
b109bf7ddc
commit
c32ef12c8e
4
LICENSE
4
LICENSE
@ -1,4 +1,6 @@
|
||||
Copyright 2016 SmartBear Software
|
||||
Copyright 2018 OpenAPI-Generator Contributors
|
||||
|
||||
Copyright 2018 SmartBear Software
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
|
||||
245
customization.md
Normal file
245
customization.md
Normal file
@ -0,0 +1,245 @@
|
||||
## Customization
|
||||
### Modifying the client library format
|
||||
|
||||
Don't like the default client syntax? Want a different language supported? No problem! OpenAPI Generator processes mustache templates with the [jmustache](https://github.com/samskivert/jmustache) engine. You can modify our templates or make your own.
|
||||
|
||||
You can look at `modules/openapi-generator/src/main/resources/${your-language}` for examples. To make your own templates, create your own files and use the `-t` flag to specify your template folder. It actually is that easy.
|
||||
|
||||
### Making your own codegen modules
|
||||
|
||||
If you're starting a project with a new language and don't see what you need, openapi-generator can help you create a project to generate your own libraries:
|
||||
|
||||
```sh
|
||||
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar meta \
|
||||
-o output/myLibrary -n myClientCodegen -p com.my.company.codegen
|
||||
```
|
||||
|
||||
This will write, in the folder `output/myLibrary`, all the files you need to get started, including a `README.md. Once modified and compiled, you can load your library with the codegen and generate clients with your own, custom-rolled logic.
|
||||
|
||||
You would then compile your library in the `output/myLibrary` folder with `mvn package` and execute the codegen like such:
|
||||
|
||||
```sh
|
||||
java -cp output/myLibrary/target/myClientCodegen-openapi-generator-1.0.0.jar:modules/openapi-generator-cli/target/openapi-generator-cli.jar org.openapitools.codegen.OpenAPIGenerator
|
||||
```
|
||||
For Windows users, you will need to use `;` instead of `:` in the classpath, e.g.
|
||||
```
|
||||
java -cp output/myLibrary/target/myClientCodegen-openapi-generator-1.0.0.jar;modules/openapi-generator-cli/target/openapi-generator-cli.jar org.openapitools.codegen.OpenAPIGenerator
|
||||
```
|
||||
|
||||
Note the `myClientCodegen` is an option now, and you can use the usual arguments for generating your library:
|
||||
|
||||
```sh
|
||||
java -cp output/myLibrary/target/myClientCodegen-openapi-generator-1.0.0.jar:modules/openapi-generator-cli/target/openapi-generator-cli.jar \
|
||||
io.openapitools.codegen.OpenAPIGenerator generate -l myClientCodegen\
|
||||
-i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
|
||||
-o myClient
|
||||
```
|
||||
|
||||
|
||||
### Selective generation
|
||||
You may not want to generate *all* models in your project. Likewise you may want just one or two apis to be written. If that's the case, you can use system properties to control the output:
|
||||
|
||||
The default is generate *everything* supported by the specific library. Once you enable a feature, it will restrict the contents generated:
|
||||
|
||||
```sh
|
||||
# generate only models
|
||||
java -Dmodels {opts}
|
||||
|
||||
# generate only apis
|
||||
java -Dapis {opts}
|
||||
|
||||
# generate only supporting files
|
||||
java -DsupportingFiles
|
||||
|
||||
# generate models and supporting files
|
||||
java -Dmodels -DsupportingFiles
|
||||
```
|
||||
|
||||
To control the specific files being generated, you can pass a CSV list of what you want:
|
||||
```sh
|
||||
# generate the User and Pet models only
|
||||
-Dmodels=User,Pet
|
||||
|
||||
# generate the User model and the supportingFile `StringUtil.java`:
|
||||
-Dmodels=User -DsupportingFiles=StringUtil.java
|
||||
```
|
||||
|
||||
To control generation of docs and tests for api and models, pass false to the option. For api, these options are `-DapiTests=false` and `-DapiDocs=false`. For models, `-DmodelTests=false` and `-DmodelDocs=false`.
|
||||
These options default to true and don't limit the generation of the feature options listed above (like `-Dapi`):
|
||||
|
||||
```sh
|
||||
# generate only models (with tests and documentation)
|
||||
java -Dmodels {opts}
|
||||
|
||||
# generate only models (with tests but no documentation)
|
||||
java -Dmodels -DmodelDocs=false {opts}
|
||||
|
||||
# generate only User and Pet models (no tests and no documentation)
|
||||
java -Dmodels=User,Pet -DmodelTests=false {opts}
|
||||
|
||||
# generate only apis (without tests)
|
||||
java -Dapis -DapiTests=false {opts}
|
||||
|
||||
# generate only apis (modelTests option is ignored)
|
||||
java -Dapis -DmodelTests=false {opts}
|
||||
```
|
||||
|
||||
When using selective generation, _only_ the templates needed for the specific generation will be used.
|
||||
|
||||
### Ignore file format
|
||||
|
||||
OpenAPI Generator supports a `.openapi-generator-ignore` file, similar to `.gitignore` or `.dockerignore` you're probably already familiar with.
|
||||
|
||||
The ignore file allows for better control over overwriting existing files than the `--skip-overwrite` flag. With the ignore file, you can specify individual files or directories can be ignored. This can be useful, for example if you only want a subset of the generated code.
|
||||
|
||||
Examples:
|
||||
|
||||
```sh
|
||||
# OpenAPI Generator Ignore
|
||||
# Lines beginning with a # are comments
|
||||
|
||||
# This should match build.sh located anywhere.
|
||||
build.sh
|
||||
|
||||
# Matches build.sh in the root
|
||||
/build.sh
|
||||
|
||||
# Exclude all recursively
|
||||
docs/**
|
||||
|
||||
# Explicitly allow files excluded by other rules
|
||||
!docs/UserApi.md
|
||||
|
||||
# Recursively exclude directories named Api
|
||||
# You can't negate files below this directory.
|
||||
src/**/Api/
|
||||
|
||||
# When this file is nested under /Api (excluded above),
|
||||
# this rule is ignored because parent directory is excluded by previous rule.
|
||||
!src/**/PetApiTests.cs
|
||||
|
||||
# Exclude a single, nested file explicitly
|
||||
src/Org.OpenAPITools.Test/Model/AnimalFarmTests.cs
|
||||
```
|
||||
|
||||
The `.openapi-generator-ignore` file must exist in the root of the output directory.
|
||||
|
||||
Upon first code generation, you may also pass the CLI option `--ignore-file-override=/path/to/ignore_file` for greater control over generated outputs. Note that this is a complete override, and will override the `.openapi-generator-ignore` file in an output directory when regenerating code.
|
||||
|
||||
Editor support for `.openapi-generator-ignore` files is available in IntelliJ via the [.ignore plugin](https://plugins.jetbrains.com/plugin/7495--ignore).
|
||||
|
||||
### Customizing the generator
|
||||
|
||||
There are different aspects of customizing the code generator beyond just creating or modifying templates. Each language has a supporting configuration file to handle different type mappings, etc:
|
||||
|
||||
```sh
|
||||
$ ls -1 modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/
|
||||
AbstractJavaJAXRSServerCodegen.java
|
||||
AbstractTypeScriptClientCodegen.java
|
||||
... (results omitted)
|
||||
TypeScriptAngularClientCodegen.java
|
||||
TypeScriptNodeClientCodegen.java
|
||||
```
|
||||
|
||||
Each of these files creates reasonable defaults so you can get running quickly. But if you want to configure package names, prefixes, model folders, etc. you can use a json config file to pass the values.
|
||||
|
||||
```sh
|
||||
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.yaml \
|
||||
-l java \
|
||||
-o samples/client/petstore/java \
|
||||
-c path/to/config.json
|
||||
```
|
||||
and `config.json` contains the following as an example:
|
||||
```json
|
||||
{
|
||||
"apiPackage" : "petstore"
|
||||
}
|
||||
```
|
||||
|
||||
Supported config options can be different per language. Running `config-help -l {lang}` will show available options.
|
||||
**These options are applied via configuration file (e.g. config.json) or by passing them with `-D{optionName}={optionValue}`**. (If `-D{optionName}` does not work, please open a [ticket](https://github.com/openapitools/openapi-generator/issues/new) and we'll look into it)
|
||||
|
||||
```sh
|
||||
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar config-help -l java
|
||||
```
|
||||
|
||||
Output
|
||||
|
||||
```
|
||||
CONFIG OPTIONS
|
||||
modelPackage
|
||||
package for generated models
|
||||
|
||||
apiPackage
|
||||
package for generated api classes
|
||||
...... (results omitted)
|
||||
library
|
||||
library template (sub-template) to use:
|
||||
jersey1 - HTTP client: Jersey client 1.18. JSON processing: Jackson 2.4.2
|
||||
jersey2 - HTTP client: Jersey client 2.6
|
||||
feign - HTTP client: Netflix Feign 8.1.1. JSON processing: Jackson 2.6.3
|
||||
okhttp-gson (default) - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1
|
||||
retrofit - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1 (Retrofit 1.9.0)
|
||||
retrofit2 - HTTP client: OkHttp 2.5.0. JSON processing: Gson 2.4 (Retrofit 2.0.0-beta2)
|
||||
google-api-client - HTTP client: google-api-client 1.23.0. JSON processing: Jackson 2.8.9
|
||||
rest-assured - HTTP client: rest-assured : 3.1.0. JSON processing: Gson 2.6.1. Only for Java8
|
||||
```
|
||||
|
||||
Your config file for Java can look like
|
||||
|
||||
```json
|
||||
{
|
||||
"groupId":"com.my.company",
|
||||
"artifactId":"MyClient",
|
||||
"artifactVersion":"1.2.0",
|
||||
"library":"feign"
|
||||
}
|
||||
```
|
||||
|
||||
For all the unspecified options default values will be used.
|
||||
|
||||
Another way to override default options is to extend the config class for the specific language.
|
||||
To change, for example, the prefix for the Objective-C generated files, simply subclass the `ObjcClientCodegen.java`:
|
||||
|
||||
```java
|
||||
package com.mycompany.openapitools.codegen;
|
||||
|
||||
import org.openapitools.codegen.languages.*;
|
||||
|
||||
public class MyObjcCodegen extends ObjcClientCodegen {
|
||||
static {
|
||||
PREFIX = "HELO";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
and specify the `classname` when running the generator:
|
||||
|
||||
```
|
||||
-l com.mycompany.openapitools.codegen.MyObjcCodegen
|
||||
```
|
||||
|
||||
Your subclass will now be loaded and overrides the `PREFIX` value in the superclass.
|
||||
|
||||
### Bringing your own models
|
||||
|
||||
Sometimes you don't want a model generated. In this case, you can simply specify an import mapping to tell
|
||||
the codegen what _not_ to create. When doing this, every location that references a specific model will
|
||||
refer back to your classes. Note, this may not apply to all languages...
|
||||
|
||||
To specify an import mapping, use the `--import-mappings` argument and specify the model-to-import logic as such:
|
||||
|
||||
```
|
||||
--import-mappings Pet=my.models.MyPet
|
||||
```
|
||||
|
||||
Or for multiple mappings:
|
||||
|
||||
```
|
||||
--import-mappings Pet=my.models.MyPet,Order=my.models.MyOrder
|
||||
```
|
||||
or
|
||||
```
|
||||
--import-mappings Pet=my.models.MyPet --import-mappings Order=my.models.MyOrder
|
||||
```
|
||||
33
integration.md
Normal file
33
integration.md
Normal file
@ -0,0 +1,33 @@
|
||||
## Workflow Integration (Maven, Github, CI/CD)
|
||||
|
||||
### Maven Integration
|
||||
|
||||
You can use the [openapi-generator-maven-plugin](modules/openapi-generator-maven-plugin/README.md) for integrating with your workflow, and generating any codegen target.
|
||||
|
||||
### GitHub Integration
|
||||
|
||||
To push the auto-generated SDK to GitHub, we provide `git_push.sh` to streamline the process. For example:
|
||||
|
||||
1) Create a new repository in GitHub (Ref: https://help.github.com/articles/creating-a-new-repository/)
|
||||
|
||||
2) Generate the SDK
|
||||
```sh
|
||||
java -jar openapi-generator-cli.jar generate \
|
||||
-i modules/openapi-generator/src/test/resources/2_0/petstore.json -l perl \
|
||||
--git-user-id "wing328" \
|
||||
--git-repo-id "petstore-perl" \
|
||||
--release-note "Github integration demo" \
|
||||
-o /var/tmp/perl/petstore
|
||||
```
|
||||
3) Push the SDK to GitHub
|
||||
```sh
|
||||
cd /var/tmp/perl/petstore
|
||||
/bin/sh ./git_push.sh
|
||||
```
|
||||
### CI/CD
|
||||
|
||||
Some generators also generate CI/CD configuration files (.travis.yml) so that the output will be ready to be tested by the CI (e.g. Travis)
|
||||
|
||||
If you're looking for the configuration files of a particular CI that is not yet supported, please open an [issue](https://github.com/swagger-api/swagger-codegen/issues/new) to let us know.
|
||||
|
||||
[Back to OpenAPI-Generator's README page](README.md)
|
||||
77
online-openapi-generator.md
Normal file
77
online-openapi-generator.md
Normal file
@ -0,0 +1,77 @@
|
||||
## Online OpenAPI generator
|
||||
|
||||
One can also generate API client or server using the online openapi-generator.
|
||||
|
||||
Here are the steps to run it locally:
|
||||
```
|
||||
mvn clean install
|
||||
cd openapi-generator-online
|
||||
mvn jetty:run
|
||||
```
|
||||
|
||||
For example, to generate Ruby API client, simply send the following HTTP request using curl:
|
||||
```sh
|
||||
curl -X POST -H "content-type:application/json" -d '{"swaggerUrl":"https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' https://localhost:8080/api/gen/clients/ruby
|
||||
```
|
||||
Then you will receieve a JSON response with the URL to download the zipped code.
|
||||
|
||||
To customize the SDK, you can `POST` to `https://localhost:8080/gen/clients/{language}` with the following HTTP body:
|
||||
```json
|
||||
{
|
||||
"options": {},
|
||||
"swaggerUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
|
||||
}
|
||||
```
|
||||
in which the `options` for a language can be obtained by submitting a `GET` request to `https://locahost:8080/api/gen/clients/{language}`:
|
||||
|
||||
For example, `curl https://localhost:8080/api/gen/clients/python` returns
|
||||
```json
|
||||
"packageName":{
|
||||
"opt":"packageName",
|
||||
"description":"python package name (convention: snake_case).",
|
||||
"type":"string",
|
||||
"default":"openapi_client"
|
||||
},
|
||||
"packageVersion":{
|
||||
"opt":"packageVersion",
|
||||
"description":"python package version.",
|
||||
"type":"string",
|
||||
"default":"1.0.0"
|
||||
},
|
||||
"sortParamsByRequiredFlag":{
|
||||
"opt":"sortParamsByRequiredFlag",
|
||||
"description":"Sort method arguments to place required parameters before optional parameters.",
|
||||
"type":"boolean",
|
||||
"default":"true"
|
||||
}
|
||||
|
||||
{}
|
||||
```
|
||||
To set package name to `pet_store`, the HTTP body of the request is as follows:
|
||||
```json
|
||||
{
|
||||
"options": {
|
||||
"packageName": "pet_store"
|
||||
},
|
||||
"swaggerUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
|
||||
}
|
||||
```
|
||||
and here is the curl command:
|
||||
```sh
|
||||
curl -H "Content-type: application/json" -X POST -d '{"options": {"packageName": "pet_store"},"swaggerUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' https://localhost:8080/api/gen/clients/python
|
||||
```
|
||||
|
||||
Instead of using `swaggerUrl` with an URL to the OpenAPI spec, one can include the spec in the JSON payload with `spec`, e.g.
|
||||
```json
|
||||
{
|
||||
"options": {},
|
||||
"spec": {
|
||||
"swagger": "2.0",
|
||||
"info": {
|
||||
"version": "1.0.0",
|
||||
"title": "Test API"
|
||||
},
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user