Swagger Codegen使用
- Java
- 17天前
- 37热度
- 0评论
swagger codegen自动生成retrofit代码。
1、基础使用
1.1、下载swagger-codegen-cli.jar
下载地址：https://oss.sonatype.org/content/repositories/snapshots/io/swagger/swagger-codegen-cli/3.0.0-SNAPSHOT/
下载下来的的文件名带有和版号，“swagger-codegen-cli-3.0.0-20170727.jar”。觉得文件名太长，可以重命名，如：swagger-codegen-cli.jar
1.2、编写配置文件（可选）
新建个文件命名为config.json，在config.json文件中添加如下内容
{
"library": "retrofit2",
"useRxJava2": "true",
"developerName": "leix",
"developerEmail": "",
"developerOrganization": "albani.com",
"invokerPackage": "com.albani.app",
"modelPackage": "com.albani.app.data.entity",
"apiPackage": "com.albani.app.data.api",
"artifactId": "swagger-petstore-retrofit2"
}
library，生成的代码支付的类，有jersey1、jersey2、okhttp-gson、resttemplate、resteasy、feign、retrofit、retrofit2等几种类型，我们选择的retrofit2
developerName，开发者名字，会出现在代码文件里
developerEmail，开发者邮箱，会出现在代码文件里
developrOrganization，开发者组织，会出现在代码里
invokerPackage，项目的包名
apiPackage，生成的***Api.java文件的包名
modelPackage，生成的数据模型java文件包名
dateLibrary，时间使用的类开
useRxJava，是否使用rxjava生成api接口
useRxJava2，是否使用rxjava2的方式调用接口，在这里我们设为true
1.3、准备swagger.json
json文件和yml文件都是可以的，所以用editor生成swagger.json或swagger.yml
1.4、执行生成
java -jar swagger-codegen-cli.jar generate -i swagger.json -o client -l java -c config.json
-i 表示输入的文件，editor生成的设计文件路径，如：-i d:/swagger/swagger.json
-o 代码生成目录，swagger codegen把代码生成到什么地方，如：-o d:/swagger/client
-l 生成代码语言，我们是生成java，如：-l java
-c 配置文件，配制文件路径，如：-c d:/swagger/config.json
2、参数说明
NAME
swagger-codegen-cli generate - Generate code with chosen lang
SYNOPSIS
swagger-codegen-cli generate
[(-a <authorization> | --auth <authorization>)]
[--additional-properties <additional properties>...]
[--api-package <api package>] [--artifact-id <artifact id>]
[--artifact-version <artifact version>]
[(-c <configuration file> | --config <configuration file>)]
[-D <system properties>...] [--git-repo-id <git repo id>]
[--git-user-id <git user id>] [--group-id <group id>]
[--http-user-agent <http user agent>]
(-i <spec file> | --input-spec <spec file>)
[--ignore-file-override <ignore file override location>]
[--import-mappings <import mappings>...]
[--instantiation-types <instantiation types>...]
[--invoker-package <invoker package>]
(-l <language> | --lang <language>)
[--language-specific-primitives <language specific primitives>...]
[--library <library>] [--model-name-prefix <model name prefix>]
[--model-name-suffix <model name suffix>]
[--model-package <model package>]
[(-o <output directory> | --output <output directory>)]
[--release-note <release note>] [--remove-operation-id-prefix]
[--reserved-words-mappings <reserved word mappings>...]
[(-s | --skip-overwrite)]
[(-t <template directory> | --template-dir <template directory>)]
[--type-mappings <type mappings>...] [(-v | --verbose)]
OPTIONS
-a <authorization>, --auth <authorization>
adds authorization headers when fetching the swagger definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
--additional-properties <additional properties>
sets additional properties that can be referenced by the mustache
templates in the format of name=value,name=value. You can also have
multiple occurrences of this option.
--api-package <api package>
package for generated api classes
--artifact-id <artifact id>
artifactId in generated pom.xml
--artifact-version <artifact version>
artifact version in generated pom.xml
-c <configuration file>, --config <configuration file>
Path to json configuration file. File content should be in a json
format {"optionKey":"optionValue", "optionKey1":"optionValue1"...}
Supported options can be different for each language. Run
config-help -l {lang} command for language specific config options.
-D <system properties>
sets specified system properties in the format of
name=value,name=value (or multiple options, each with name=value)
--git-repo-id <git repo id>
Git repo ID, e.g. swagger-codegen.
--git-user-id <git user id>
Git user ID, e.g. swagger-api.
--group-id <group id>
groupId in generated pom.xml
--http-user-agent <http user agent>
HTTP user agent, e.g. codegen_csharp_api_client, default to
'Swagger-Codegen/{packageVersion}}/{language}'
-i <spec file>, --input-spec <spec file>
location of the swagger spec, as URL or file (required)
--ignore-file-override <ignore file override location>
Specifies an override location for the .swagger-codegen-ignore file.
Most useful on initial generation.
--import-mappings <import mappings>
specifies mappings between a given class and the import that should
be used for that class in the format of type=import,type=import. You
can also have multiple occurrences of this option.
--instantiation-types <instantiation types>
sets instantiation type mappings in the format of
type=instantiatedType,type=instantiatedType.For example (in Java):
array=ArrayList,map=HashMap. In other words array types will get
instantiated as ArrayList in generated code. You can also have
multiple occurrences of this option.
--invoker-package <invoker package>
root package for generated code
-l <language>, --lang <language>
client language to generate (maybe class name in classpath,
required)
--language-specific-primitives <language specific primitives>
specifies additional language specific primitive types in the format
of type1,type2,type3,type3. For example:
String,boolean,Boolean,Double. You can also have multiple
occurrences of this option.
--library <library>
library template (sub-template)
--model-name-prefix <model name prefix>
Prefix that will be prepended to all model names. Default is the
empty string.
--model-name-suffix <model name suffix>
Suffix that will be appended to all model names. Default is the
empty string.
--model-package <model package>
package for generated models
-o <output directory>, --output <output directory>
where to write the generated files (current dir by default)
--release-note <release note>
Release note, default to 'Minor update'.
--remove-operation-id-prefix
Remove prefix of operationId, e.g. config_getId => getId
--reserved-words-mappings <reserved word mappings>
specifies how a reserved name should be escaped to. Otherwise, the
default _<name> is used. For example id=identifier. You can also
have multiple occurrences of this option.
-s, --skip-overwrite
specifies if the existing files should be overwritten during the
generation.
-t <template directory>, --template-dir <template directory>
folder containing the template files
--type-mappings <type mappings>
sets mappings between swagger spec types and generated code types in
the format of swaggerType=generatedType,swaggerType=generatedType.
For example: array=List,map=Map,string=String. You can also have
multiple occurrences of this option.
-v, --verbose
verbose mode
3、配置文件说明
CONFIG OPTIONS
sortParamsByRequiredFlag
Sort method arguments to place required parameters before optional parameters. (Default: true)
ensureUniqueParams
Whether to ensure parameter names are unique in an operation (rename parameters that are not). (Default: true)
allowUnicodeIdentifiers
boolean, toggles whether unicode identifiers are allowed in names or not, default is false (Default: false)
modelPackage
package for generated models
apiPackage
package for generated api classes
invokerPackage
root package for generated code
groupId
groupId in generated pom.xml
artifactId
artifactId in generated pom.xml
artifactVersion
artifact version in generated pom.xml
artifactUrl
artifact URL in generated pom.xml
artifactDescription
artifact description in generated pom.xml
scmConnection
SCM connection in generated pom.xml
scmDeveloperConnection
SCM developer connection in generated pom.xml
scmUrl
SCM URL in generated pom.xml
developerName
developer name in generated pom.xml
developerEmail
developer email in generated pom.xml
developerOrganization
developer organization in generated pom.xml
developerOrganizationUrl
developer organization URL in generated pom.xml
licenseName
The name of the license
licenseUrl
The URL of the license
sourceFolder
source folder for generated code
localVariablePrefix
prefix for generated code members and local variables
serializableModel
boolean - toggle "implements Serializable" for generated models (Default: false)
bigDecimalAsString
Treat BigDecimal values as Strings to avoid precision loss. (Default: false)
fullJavaUtil
whether to use fully qualified name for classes under java.util. This option only works for Java API client (Default: false)
hideGenerationTimestamp
hides the timestamp when files were generated
withXml
whether to include support for application/xml content type. This option only works for Java API client (resttemplate) (Default: false)
dateLibrary
Option. Date library to use
joda - Joda (for legacy app only)
legacy - Legacy java.util.Date (if you really have a good reason not to use threetenbp
java8-localdatetime - Java 8 using LocalDateTime (for legacy app only)
java8 - Java 8 native JSR310 (preferred for jdk 1.8+) - note: this also sets "java8" to true
threetenbp - Backport of JSR310 (preferred for jdk < 1.8)
java8
Option. Use Java8 classes instead of third party equivalents
true - Use Java 8 classes such as Base64
false - Various third party libraries as needed
useRxJava
Whether to use the RxJava adapter with the retrofit2 library. (Default: false)
useRxJava2
Whether to use the RxJava2 adapter with the retrofit2 library. (Default: false)
parcelableModel
Whether to generate models for Android that implement Parcelable with the okhttp-gson library. (Default: false)
usePlay24WS
Use Play! 2.4 Async HTTP client (Play WS API) (Default: false)
supportJava6
Whether to support Java6 with the Jersey1 library. (Default: false)
useBeanValidation
Use BeanValidation API annotations (Default: false)
performBeanValidation
Perform BeanValidation (Default: false)
useGzipFeature
Send gzip-encoded requests (Default: false)
useRuntimeException
Use RuntimeException instead of Exception (Default: false)
library
library template (sub-template) to use (Default: okhttp-gson)
jersey1 - HTTP client: Jersey client 1.19.4. JSON processing: Jackson 2.8.9. Enable Java6 support using '-DsupportJava6=true'. Enable gzip request encoding using '-DuseGzipFeature=true'.
feign - HTTP client: OpenFeign 9.4.0. JSON processing: Jackson 2.8.9
jersey2 - HTTP client: Jersey client 2.25.1. JSON processing: Jackson 2.8.9
okhttp-gson - HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.8.1. Enable Parcelable models on Android using '-DparcelableModel=true'. Enable gzip request encoding using '-DuseGzipFeature=true'.
retrofit - HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.3.1 (Retrofit 1.9.0). IMPORTANT NOTE: retrofit1.x is no longer actively maintained so please upgrade to 'retrofit2' instead.
retrofit2 - HTTP client: OkHttp 3.8.0. JSON processing: Gson 2.6.1 (Retrofit 2.3.0). Enable the RxJava adapter using '-DuseRxJava[2]=true'. (RxJava 1.x or 2.x)
resttemplate - HTTP client: Spring RestTemplate 4.3.9-RELEASE. JSON processing: Jackson 2.8.9
resteasy - HTTP client: Resteasy client 3.1.3.Final. JSON processing: Jackson 2.8.9
