随着业务的发展传统软件架构往往会面临复杂性高、可靠性差、扩展能力受限、阻碍技术创新等诸多问题，而一条有效的解决途径就是将传统软件按功能进行微服务化。微服务化后，每个服务运行在自己的进程中，并使用轻量级机制通信，通常是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("[email protected]")
                .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：作用在方法上，表示单独的请求参数。 有以下几个属性