Swagger的使用

Swagger

Swagger是什么？

简单的来说就是一款自动生成API文档并且支持在线调试的一个十分实用的工具。

通过Swagger规定的规范去定义接口几接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以生成各种格式的接口文档。

对于程序员来说，最难受的就是需要自己写接口文档等一系列其他文档，但是最最难受的就是别人不写文档。
尤其是现在对于前后端分离，如果接口调用不同意，一会儿加一个字段一会儿少一个字段，那真的是会分分钟要人命。
所以出现了Swagger，这个可以用于生成，描述，调用和可视化RESTful风格的Web服务。
总的来说，Swagger的功能就两个:

1. 接口的文档在线自动生成
2. 功能测试

SpringBoot集成Swagger

1. 引入依赖

       <!-- swagger -->
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>版本号需要注意</version>
       </dependency>
       <!-- swagger-ui -->
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>版本号需要注意</version>
       </dependency>
   

相关配置

	```
	server:
	  port: 8080
	  servlet:
	    context-path: /
	spring:
	  datasource:
	    url: jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=UTF-8&zeroDateTimeBehavior=convertToNull&allowMultiQueries=true&useSSL=false
	    username: root
	    password: 123456
	  jpa:
	    database: MySQL
	    database-platform: org.hibernate.dialect.MySQL5InnoDBDialect
	    show-sql: true
	    hibernate:
	      ddl-auto: update
	```

2. 使用注解来启动Swagger，同时需要进行配置

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig{
   	//一个Docket就是一组Group
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   //为当前包路径
                   .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                   .paths(PathSelectors.any())
                   .build();
       }
       //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   //页面标题
                   .title("标题")
                   //创建人
                   .contact(new Contact("名字", "url", ""))
                   //版本号
                   .version("1.0")
                   //描述
                   .description("描述")
                   .build();
       }
   }
   

3. 配置Controller
   也就是需要在Controller类上加上各种各样辅助生成API接口文档的注释
   常见的注释使用：

注释	作用	使用方式	参数
@Api	标识这个类是Swagger的资源	用于类	tags:表示说明，value：也是表示说明
@ApiModel	对类进行说明，用于参数用实体类接收	用于实体类	value:表示对象名,description:描述
@ApiOperation	标识一个http请求的操作	用于方法	value：方法描述，notes：提示内容，tags：可以重新分组
@ApiImplicitParams	表示单独的请求参数	用于方法	name：参数名，value：参数说明，dataType：数据类型，paramType：参数类型，example：举例说明
@ApiParam	标识对参数添加元素据	用于方法，参数，字段	required：是否必须填写，name：参数名，value：参数说明

产生的结果：需要通过访问 你的主机地址例如 http://localhost:8080/swagger-ui.html


就会产生这样的效果。
基本的Swagger的使用就是这样了。
Swagger注解是其中的关键，引入的是此处的图片的一张图：