我和我的项目之整合Swagger2

写在前面：

之前，第一次见到Swagger时还是在我第一家公司，看着这高大上的页面所有接口都可以罗列出来，居然也还可以在线进行API调试。那是便对这充满了好奇，心里一直想尝试着自己能搞出来。随着经验的步步增长做的东西越来越多接触到的内容也越来越多。对Swagger的理解也越来越透彻。这篇文章就讲讲我曾经梦寐以求想搞出来的Swagger。

Swagger的由来

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

一位不愿透露姓名的男子在网上找的一段定义

------------------废话不多说。整代码。--------------------------

Pom.xml

Ps:之前也不知道是Swagger新版本不兼容的问题还是其里面的配置冲突问题，搞来搞去都不行。后来网上找到这个“忽略原版本的swagger-annotations和swagger-models，添加1.5.21版本的”发现就行了。说明下 我现在的SB版本是2.2.6。

<!--添加Swagger2 忽略原版本的swagger-annotations和swagger-models，添加1.5.21版本的-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!--解决进入swagger页面报类型转换错误，排除2.9.2中的引用，手动增加1.5.21版本-->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.21</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>
</dependency>

 Swagger2Config

工欲善其事必先利其器，往往添加了新的pom后便是配置其配置类。Swagger也不例外。

①通过@Configuration注解，让Spring来加载该配置类

②再通过@EnableSwagger2注解来启动Swagger2

@Configuration
@EnableSwagger2
public class Swagger2Config {
      ......
}

③再往Swagger2Config中通过createRestApi函数创建Docket的Bean

@Bean
public Docket createRestApi(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
            //本例采用指定扫描的注解来定义，Swagger会扫描该注解的所有定义的API，并产生文档内容
            .select()
            //扫描所有带有@RestController注解的API
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            //.apis(RequestHandlerSelectors.basePackage("com.didispace.web"))
            //采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
            .paths(PathSelectors.any())
            .build();
}
//apiInfo()用来创建该API的基本信息(这些基本信息会展现在文档页面中)
private ApiInfo apiInfo(){
    return new ApiInfoBuilder()
            .title("Swagger2API文档")
            .description("restful风格")
            .version("1.0")
            .build();
}

*放开Security监控Swagger

Ps:我项目里用到了Security，需要在config配置中放开对Swagger的权限。网上找到这段贴进去即可。

"/v2/api-docs", "/configuration/ui", "/swagger-resources", "/configuration/security", "/swagger-ui.html", "/webjars/**","/swagger-resources/configuration/ui","/swagger-ui.html"

新建一个带有@RestController注解的Controller。我这里建了一个SysUserController。它能被Swagger2Config扫描带有@RestController的类检测到。

例如下面这个需求“超级管理员能查看所有角色列表 非超级管理员只能查看自己角色”。一个普通Get请求。参数这里只是便于演示Swagger在页面上展示每个入参的含义。真正逻辑重点在方法体里，获取当前登录用户信息。

在浏览器中打开http://127.0.0.1:8181/api/swagger-ui.html主页地址（记得换成自己的ip，端口还有接口前缀哦），即可看到对应参数信息。点击“try it out”还能在线模拟发送请求哦。

整理了一段Swagger注解参考。大部能涵盖90%开发中注解的参数了。

@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置"


@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"


@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="int"
defaultValue：参数的默认值


@ApiResponses：~~ ***用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类


@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性


[swagger中参数为数组dataType的设置
https://blog.csdn.net/KingJin_CSDN_/article/details/81536315?utm_source=blogxgwz0]

Ps:完整代码参考 我码云地址：https://gitee.com/lth1024/Security/tree/muster/

Nice~