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文件，如下

  <!-- https://mvnrepository.com/artifact/io.swagger/swagger-codegen -->

  <dependency>

    <groupId>io.swagger</groupId>

    <artifactId>swagger-codegen</artifactId>

    <version>2.2.1</version>

  </dependency>

  放到本地目录（比如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添加依赖(仅操作一次)

<!-- swagger-begin -->

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-jaxrs</artifactId>
  <version>1.5.9</version>
</dependency>
<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-annotations</artifactId>
  <version>1.5.9</version>
</dependency>
<dependency>
  <groupId>com.squareup.okhttp</groupId>
  <artifactId>okhttp</artifactId>
  <version>2.7.5</version>
</dependency>
<dependency>
  <groupId>com.squareup.okhttp</groupId>
  <artifactId>logging-interceptor</artifactId>
  <version>2.7.5</version>
</dependency>
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.6.2</version>
</dependency>
<dependency>
  <groupId>joda-time</groupId>
  <artifactId>joda-time</artifactId>
  <version>2.9.3</version>
</dependency>
<!-- swagger-end -->

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 <command> [<args>]

  常用命令如下:
  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 <command>' 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 <authorization>

    当获取远程swagger定义时,添加授权头信息;URL-encoded格式化的name,逗号隔开的多个值;

  --auth <authorization>

    同 -a;

  --additional-properties <additional properties>

    设置额外的属性供模版使用;格式为name=value,name=value;

  --api-package <api package>

    指定生成的api类的包名;

  --artifact-id <artifact id>

    指定pom.xml的artifactId的值;

  --artifact-version <artifact version>

    指定pom.xml的artifact的版本;

  -c <configuration file>

    json格式的配置文件的路径;文件为json格式,支持的配置项因语言的不同而不同;

    执行 config-help -l {lang} 命令查看详细的配置项;

  --config <configuration file>

    同 -c;

  -D <system properties>

    指定系统属性,格式为name=value,name=value;

  --group-id <group id>

    指定pom.xml的groupId的值;

  -i <spec file>

    指定swagger描述文件的路径,url地址或路径文件;该参数为必须;

  --input-spec <spec file>

    同 -i;

  --import-mappings <import mappings>

    specifies mappings between a given class and the import that should be used for that class,

    格式type=import,type=import;

  --instantiation-types <instantiation types>

    设置实例类型映射,格式type=instantiatedType,type=instantiatedType.

    例如(in Java):array=ArrayList,map=HashMap.换句话说,生成代码时,array类型会实例化为ArrayList;

  --invoker-package <invoker package>

    指定根包名称;

  -l <language>

    指定生成客户端代码的语言,该参数为必须;

  --lang <language>

    同 -l;

  --language-specific-primitives <language specific primitives>

    指定附加语言特定的原始类型,格式type1,type2,type3,type3.例如:String,boolean,Boolean,Double;

  --library <library>

    library template (sub-template);

  --model-package <model package>

    指定生成的model类的包名;

  -o <output directory>

    指定生成文件的位置(默认当前目录);

  --output <output directory>

    同 -o;

  -s

    指定该参数表示不覆盖已经存在的文件;

  --skip-overwrite

    同 -s;

  -t <template directory>

    指定模版文件所在目录;

  --template-dir <template directory>

    同 -t;

  --type-mappings <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的数据类型进行映射；