java codegen_swagger-codegen生成java客户端代码
前后端分离的时候，需要建立契约，Swagger可达到该目的(略)。
建立Rest接口后，通过swagger-codegen项目可以自动生成对应的客户端代码(c++、php、java、js、node等等)，
关于swagger-codegen项目的使用，发现中文文档较少，追根述源后，发现其中相当一部分同出一辙。
亲自摸索使用后，记录一下步骤，利己利人。
swagger-codegen项目地址: https://github.com/swagger-api/swagger-codegen
项目文档(README.md)说的比较详细，但是重复的地方太多，容易让新手搞晕。
其实，文档内容可以简化为如下步骤(凡‘略’，皆不予理睬)：
【注意】以下步骤，均在Windows系统中操作，生成java客户端代码，其他语言类似；英文不好，有些不会翻译，故保留英文原文；
1、Table of contents(略)
2、Compatibility(略)
3、Prerequisites
3.1、从maven仓库下载swagger-codegen的jar文件，如下
io.swagger
swagger-codegen
2.2.1
放到本地目录(比如D:\env\swagger-codegen-cli-2.2.1.jar)；
3.2、本机安装JDK7+，并设置$PATH(比如：D:\Java\jdk1.8.0_60\bin;)；
3.3、本机安装Maven3.3.3+，并设置$PATH(比如：D:\apache-maven-3.3.3\bin;)；
4、Building(略)
5、Docker(略)
6、Homebrew(略)
7、Getting Started
dos窗口中，执行如下命令(Windows系统下，换行符无效，必须写在同一行)：
java -jar D:\env\swagger-codegen-cli-2.2.1.jar generate
-i http://petstore.swagger.io/v2/swagger.json
-l java
-o D:\swagger-client
--model-package com.xxx.client.model
--api-package com.xxx.client.api
【参数说明】
-jar 指定 swagger-codegen-cli-2.2.1.jar 的位置，绝对路径、相对路径均可；
-i 指定 swagger.json 的位置，本地路径、网络路径均可；
-l 指定客户端代码的语言；
-o 指定代码生成的位置；
--model-package 指定model代码的包名；
--api-package 指定api代码的包名；
8、Workflow Integration(略)
9、Github Integration(略)
【补充后续操作步骤】
10、将生成的代码拷贝到项目中(api、model、test)
11、pom.xml添加依赖(仅操作一次)
io.swagger
swagger-jaxrs
1.5.9
io.swagger
swagger-annotations
1.5.9
com.squareup.okhttp
okhttp
2.7.5
com.squareup.okhttp
logging-interceptor
2.7.5
com.google.code.gson
gson
2.6.2
joda-time
joda-time
2.9.3
12、修改ApiClient.java(一般来说,该文件无须覆盖,仅操作一次)
12.1、修改属性 basePath的值，自己的api根路径；
12.2、如果需要ssl，或者url追加token，需要修改 buildUrl()方法；
13、执行测试代码即可(生成的测试代码,方法体是空的,需要自己补充代码)；
【补充】
A、下载源代码：
下载最新代码
> git clone https://github.com/swagger-api/swagger-codegen.git
下载指定版本
> git clone --branch v2.2.1 https://github.com/swagger-api/swagger-codegen.git
B、查看swagger-codegen支持的命令
> java -jar swagger-codegen-cli-2.2.1.jar help
用法: swagger-codegen-cli []
常用命令如下:
config-help 指定客户端语言的可选项说明
generate 生成客户端代码命令
help 帮助
langs 显式所有支持的语言
meta MetaGenerator. Generator for creating a new template set and configuration for Codegen. The output will be based on the language you specify, and includes default templates to include.
See 'swagger-codegen-cli help ' for more information on a specific command.
C、查看swagger-codegen的generate命令的可选项
> java -jar swagger-codegen-cli-2.2.1.jar help generate
NAME
swagger-codegen-cli generate - Generate code with chosen lang
SYNOPSIS
swagger-codegen-cli generate [options]
OPTIONS
-a
当获取远程swagger定义时,添加授权头信息;URL-encoded格式化的name,逗号隔开的多个值;
--auth
同 -a;
--additional-properties
设置额外的属性供模版使用;格式为name=value,name=value;
--api-package
指定生成的api类的包名;
--artifact-id
指定pom.xml的artifactId的值;
--artifact-version
指定pom.xml的artifact的版本;
-c
json格式的配置文件的路径;文件为json格式,支持的配置项因语言的不同而不同;
执行 config-help -l {lang} 命令查看详细的配置项;
--config
同 -c;
-D
指定系统属性,格式为name=value,name=value;
--group-id
指定pom.xml的groupId的值;
-i
指定swagger描述文件的路径,url地址或路径文件;该参数为必须;
--input-spec
同 -i;
--import-mappings
specifies mappings between a given class and the import that should be used for that class,
格式type=import,type=import;
--instantiation-types
设置实例类型映射,格式type=instantiatedType,type=instantiatedType.
例如(in Java):array=ArrayList,map=HashMap.换句话说,生成代码时,array类型会实例化为ArrayList;
--invoker-package
指定根包名称;
-l
指定生成客户端代码的语言,该参数为必须;
--lang
同 -l;
--language-specific-primitives
指定附加语言特定的原始类型,格式type1,type2,type3,type3.例如:String,boolean,Boolean,Double;
--library
library template (sub-template);
--model-package
指定生成的model类的包名;
-o
指定生成文件的位置(默认当前目录);
--output
同 -o;
-s
指定该参数表示不覆盖已经存在的文件;
--skip-overwrite
同 -s;
-t
指定模版文件所在目录;
--template-dir
同 -t;
--type-mappings
设置swagger类型与生成的代码类型之间的映射,格式swaggerType=generatedType,swaggerType=generatedType.
例如: array=List,map=Map,string=String;
-v
指定verbose mode;
--verbose
同 -v;
D、查看java客户端的可配置项
> java -jar swagger-codegen-cli-2.2.1.jar config-help -l java
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)
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
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
dateLibrary
Option. Date library to use
joda - Joda
legacy - Legacy java.util.Date
java8-localdatetime - Java 8 using LocalDateTime (for legacy app only)
java8 - Java 8 native
useRxJava
Whether to use the RxJava adapter with the retrofit2 library. (Default: false)
library
library template (sub-template) to use (Default: okhttp-gson)
jersey1 - HTTP client: Jersey client 1.19.1. JSON processing: Jackson 2.7.0
feign - HTTP client: Netflix Feign 8.16.0. JSON processing: Jackson 2.7.0
jersey2 - HTTP client: Jersey client 2.22.2. JSON processing: Jackson 2.7.0
okhttp-gson - HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.6.2
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.2.0. JSON processing: Gson 2.6.1 (Retrofit 2.0.2).
Enable the RxJava adapter using '-DuseRxJava=true'. (RxJava 1.1.3)
E、查看swagger-codegen支持的客户端语言
> java -jar swagger-codegen-cli-2.2.1.jar langs
(结果略)
或参考 https://github.com/swagger-api/swagger-codegen/wiki/API-client-generator-HOWTO
F、服务器端代码生成，参考https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO
G、swagger支持的数据类型映射
http://swagger.io/specification/
参考代码：DefaultCodegen.java
this.typeMapping = new HashMap();
this.typeMapping.put("array", "List");
this.typeMapping.put("map", "Map");
this.typeMapping.put("List", "List");
this.typeMapping.put("boolean", "Boolean");
this.typeMapping.put("string", "String");
this.typeMapping.put("int", "Integer");
this.typeMapping.put("float", "Float");
this.typeMapping.put("number", "BigDecimal");
this.typeMapping.put("DateTime", "Date");
this.typeMapping.put("long", "Long");
this.typeMapping.put("short", "Short");
this.typeMapping.put("char", "String");
this.typeMapping.put("double", "Double");
this.typeMapping.put("object", "Object");
this.typeMapping.put("integer", "Integer");
this.typeMapping.put("ByteArray", "byte[]");
this.typeMapping.put("binary", "byte[]");
遗留问题：
1、还不清楚如何将api数据类型和java的数据类型进行映射；
--------------------- 本文来自 wangjunjun2008 的CSDN 博客 ，全文地址请点击：https://blog.csdn.net/wangjunjun2008/article/details/53200437?utm_source=copy