随着业务的发展传统软件架构往往会面临复杂性高、可靠性差、扩展能力受限、阻碍技术创新等诸多问题，而一条有效的解决途径就是将传统软件按功能进行微服务化。微服务化后，每个服务运行在自己的进程中，并使用轻量级机制通信，通常是HTTP API。这样又会引入各个微服务间的API文档交互以及API调用问题。本文主要介绍在SpringBoot中使用Swagger 来自动生成API文档以及进一步使用Swagger-codegen 来生成SDK来解决这些问题。

SpringBoot集成Swagger来生成API文档

Swagger可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger也提供了强大的页面测试功能来调试每个RESTful API。

下面介绍下怎么在SpringBoot中引入Swagger

1. 加入POM依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

2. 创建Swagger 配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.aliyun.app.gdn.polardb.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多Spring Boot相关文章请关注：http://mochi.website")
                .termsOfServiceUrl("http://mochi.website")
                .contact("dongguangqing2008@126.com")
                .version("1.0")
                .build();
    }
}

通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

3. 添加文档内容

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

@RestController
@RequestMapping(value="/users")     // 通过这里配置使下面的映射都在/users下，可去除
public class UserController {

    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    @ApiOperation(value="获取用户列表", notes="")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", required = false, dataType = "Integer", paramType = "query")
    })
    @ApiResponses({
        @ApiResponse(code=400,message="请求参数没填好"),
        @ApiResponse(code=404,message="请求路径不对")
    })
    @RequestMapping(value={""}, method=RequestMethod.GET)
    public List<User> getUserList(@RequestParam() String id) {
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }
}

其中

@ApiImplicitParam：作用在方法上，表示单独的请求参数。 有以下几个属性

• name： 参数名
• value： 参数描述
• required： 参数是否必填
• dataType： 参数的数据类型
• paramType： 查询参数类型， 取值：path、query、body、header、form

@ApiImplicitParam的paramType：query、form域中的值需要使用@RequestParam获取， header域中的值需要使用@RequestHeader来获取，path域中的值需要使用@PathVariable来获取，body域中的值使用@RequestBody来获取，否则可能出错；

@ApiImplicitParams：用于方法，包含多个 @ApiImplicitParam

@ApiResponse：一般用于表达一个错误的响应信息，主要有以下几个属性

• code：数字，例如400
• message：信息，例如"请求参数没填好"
• response：抛出异常的类

@ApiResponses：用于表示一组响应, 包含多个 @ApiResponse

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html

使用swagger-codegen生成SDK

Swagger Codegen是一个开源的代码生成器，根据Swagger定义的RESTful API可以自动建立服务端和客户端的连接。项目介绍见：https://github.com/swagger-api/swagger-codegen

安装 swagger-codegen (mac os)

brew install swagger-codegen

其他os 的安装方式见： https://github.com/swagger-api/swagger-codegen#prerequisites

安装之后可以使用swagger-codegen -h 查看帮助

⇒  swagger-codegen -h
usage: swagger-codegen [-h] Command ...

named arguments:
  -h, --help             show this help message and exit

commands:
  Command                additional help
    generate             generate
    config-help          config-help
    meta                 meta
    langs                langs
    version              version

使用swagger-codegen 生成sdk

使用swagger-codegen generate -h 查看生成sdk 帮助文档， 如：

⇒  swagger-codegen generate -h
usage: swagger-codegen generate [-h] [-v []] [-l] [-o] [-i] [-t] [--template-version] [--template-engine] [-a] [-c] [-D [ [ ...]]] [-s] [--api-package] [--model-package]
                       [--model-name-prefix] [--model-name-suffix] [--instantiation-types [ [ ...]]] [--type-mappings [ [ ...]]] [--additional-properties [ [ ...]]]
                       [--import-mappings [ [ ...]]] [--ignore-import-mapping []] [--invoker-package] [--group-id] [--artifact-id] [--artifact-version] [--library]
                       [--git-user-id] [--git-repo-id] [--release-note] [--http-user-agent] [--reserved-words-mappings [ [ ...]]] [--ignore-file-override]
                       [--remove-operation-id-prefix] [-u] [--disable-examples []]

named arguments:
  -h, --help             show this help message and exit
  -l, --lang             client language to generate (maybe class name in classpath, required)
  -o, --output           where to write the generated files (current dir by default)
  -i, --input-spec       location of the swagger spec, as URL or file (required)
  ... 

常用的参数有以下几个：

• -i : 指定swagger描述文件的路径,url地址或路径文件;
• -l : 指定生成客户端代码的语言
• -o : 指定生成文件的位置(默认当前目录)

另外， 可以通过--group-id、--artifact-id 等参数指定生成项目的结构。下面给一个我常用命令的样例

swagger-codegen generate \
    -i http://11.158.128.185:9310/v2/api-docs \
    -l java \
    -o /Users/dongguangqing/TeamFile/workspace/polardb/polardb-gdn-service-api-sdk \
    --group-id com.aliyun.app \
    --artifact-id polardb-gdn-service-api-sdk \
    --artifact-version 1.0.0.0 \
    --api-package com.aliyun.app.gdn.polardb.sdk.apis \
    --invoker-package com.aliyun.app.gdn.polardb.sdk.invoker \
    --model-package com.aliyun.app.gdn.polardb.sdk.models

其中，http://11.158.128.185:9310/v2/api-docs 是SpringBoot服务器地址， api-docs 路径可以在下面截图的位置：

更多干货，欢迎关注个人博客：http://mochi.website/

附录： 参考文档

• https://www.cnblogs.com/shamo89/p/7680771.html

• https://github.com/swagger-api/swagger-codegen#os-x-users

• https://www.jdon.com/50171