Swagger2 在spring boot中的运用- API Docs在spring boot中详细配置生成及各个平台接口网络请求代码生成Swagger-codegen-cli运用

好久没有写学习博客了。在最近的工作中，学习到了一些比较好的工具。可以提高前后台工作人员，测试人员的工作效率。甚至可以给产品提供相关直观的参考。也利于版本迭代api的系统管理，现博客记录下来，有什么不足之处请各位大牛指正！

有很多因素促成了Swagger在构建RESTful API方面的快速应用。我们列出了为什么使用Swagger来设计API的最重要的部分：

• 同时设计和记录API，从而保持蓝图和文档同步。

• 通过自动生成的交互式API文档可以看到实际使用的API，从而实现人机和机器可读。

• 围绕该框架的大型综合工具生态系统，可让您超越设计，从SDK生成到测试和调试。

• 强大的开源社区支持和领导框架。

下面我们进入正题：

一、Swagger2 在spring boot中的运用（简单配置）

    了解一下Swagger：Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。
    
    下面我们来进行配置：
        首先生成一个最基本的spring boot项目：可以基于maven或者gradle
           1、maven：

               

下载创建好的项目，导入到开发工具，我这边使用的是：intellij IDEA

现在配置pom.xml 中swagger配置。2.8.0最新版本（maven springfox 查看当前使用最多和最新版本）

<!--加上swagger的依赖-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.8.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.8.0</version>
</dependency>

    2、gradle

        build.gradle中添加

         compile('io.springfox:springfox-swagger2:2.8.0')

    compile('io.springfox:springfox-swagger-ui:2.8.0')

配置好以上！下面开始进行真正swagger相关任务。

项目中配置基本的Swagger常规参数：

swagger 基本配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApiDocket(){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.gt.swaggerfirst.controller"))
                .build();
    }


    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger First Rest Api 文档")
                .description("user 模块api文档")
                .version("0.0.1")
                .termsOfServiceUrl("")
                .build();
    }
}

@Configuration spring boot中配置注解，让Spring来加载该类配置。

@EnableSwagger2  注解来启用Swagger2。

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

启动项目，输入请求地址就可以看到swagger已经生效了，目前还没有相关接口api          

swagger简单配置就是以上内容。

二、下面我们来看具体的api文档相关注解使用。

api接口如图：

    

提供便捷的api接口测试：

    

这边使用一个User相关的接口为例，先上代码结构：

详细代码：

UserController.java

@RestController
@RequestMapping(value = "/user")
@Api(value = "/user", description = "User 相关操作")
public class UserController {

    @Autowired
    private UserService userService;

    @RequestMapping(value = "/login", method = RequestMethod.POST)
    @ApiOperation(value = "/login", notes = "用户密码登录")
    @ApiImplicitParams({@ApiImplicitParam(name = "username", value = "18888888888", required = true),
            @ApiImplicitParam(name = "password", value = "88888888", required = true)})
    @ApiResponses({@ApiResponse(code = 1000, message = "成功返回码", response = ResponseResult.class),
            @ApiResponse(code = 0, message = "失败返回码", response = ResponseResult.class)})
    public ResponseResult loginByPass(@RequestBody UserEntity userEntity) {
        ResponseResult responseResult = userService.login(userEntity.getUsername(), userEntity.getPassword());
        return responseResult;
    }
}

RestController、RequestMapping  Spring boot Restful 注解

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在出入参数对象的字段上
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

对应的每一个注解，其中参数可以参考具体swagger文档！

三、利用swagger-codegen-cli

        运用swagger-cli生成对应的请求接口框架代码，给开发人员带来很大的福利，减少重复工作。提高团队开发效率

由于个人涉及android开发，现以android为例：

1、下载 swagger-codegen-cli-2.2.1.jar，相关用法可以 java -jar swagger-codegen-cli-2.2.1.jar help 

命令行打印出帮助说明

usage: swagger-codegen-cli <command> [<args>]
The most commonly used swagger-codegen-cli commands are:
    config-help   Config help for chosen lang
    generate      Generate code with chosen lang
    help          Display help information
    langs         Shows available 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.
    validate      Validate specification
    version       Show version information
See 'swagger-codegen-cli help <command>' for more information on a specific
command.

2、生成请求后台接口的相关框架代码，需要两个配置文件，

• api接口的相关json，此文件在swagger配置成功后，生成api是已经生成：v2/api-docs 中内容生成提取成api.json；
• 生成android代码是config.json配置文件，文件中包括：网络请求使用的框架（retrofit2）、Rxjava，包名等；

介绍下我们用到的几个主要参数
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

    本实例中配置json如下：      

    

{
  "library": "retrofit2",
  "useRxJava2": "true",
  "developerName": "gt",
  "developerEmail": "",
  "developerOrganization": "albani.com",
  "invokerPackage": "com.gt.app",
  "modelPackage": "com.gt.app.data.entity",
  "apiPackage": "com.gt.app.data.api",
  "artifactId": "swagger-user-retrofit2"
}

生成命令如下：

java -jar swagger-codegen-cli-2.2.1.jar generate -i api.json -o client -l java -c config.json    

见证奇迹的时刻：

生成一个client文件夹，里面就是相关android的相关接口的请求代码：

代码结构：

主要代码：

UsercontrollerApi.java

public interface UsercontrollerApi {
    /**
     * /login
     * 用户密码登录
     * @param userEntity userEntity (required)
     * @return Call<ResponseResult>
     */

    @POST("user/login")
    Call<ResponseResult> loginByPassUsingPOST(
            @Body UserEntity userEntity
    );

}

进行相关调整就可以运用到项目中！

以上内容就是swagger在日常项目中运用到的相关点。

相关源码：https://github.com/gutaowqq20081010/Swagger-first

写的不对，不好的地方请大牛指正！