SpringBoot整合Swagger

---

SpringBoot整合Swagger

前后端分离,接口需要及时协同

swagger是一个用于生成服务器接口的规范性文档、并且能够对接口进行测试的工具

1.Swagger的作用

• 生成接口说明文档
• 对接口进行测试

2.SpringBoot整合Swagger

• 2.1.添加依赖（Swagger2 \ Swagger UI )

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

• 2.2.新建config文件夹添加SwaggerConfig类，如图

package com.example.api.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 创建Swagger2的配置类
 * @Configuration 注解：表示配置类
 * @EnableSwagger2 注解：启用Swagger2
 * 1：配置生成的文档信息
 * 2：配置生成规则
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket getDocket() {

        // 创建API信息构建器
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        // 创建标题
        apiInfoBuilder.title("接口文档说明")
                // 创建描述
                .description("SpringBoot整合Swagger2")
                // 创建版本
                .version("1.0")
                // 创建联系人
                .contact(new Contact("测试", "http://www.baidu.com", "123@qq.com"));

        // 创建ApiInfo对象
        ApiInfo apiInfo = apiInfoBuilder.build();

        // 返回指定生成的文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                // 生成文档的封面信息：标题、描述、版本、联系方式
                .apiInfo(apiInfo)
                // 选择需要生成文档的接口
                .select()
                // 指定生成文档的接口范围
                .apis(RequestHandlerSelectors.basePackage("com.example.api.controller"))
                // 对哪些请求路径生成文档：any：所有
                .paths(PathSelectors.any())
                .build();
    }
}

3.查看/测试生成的接口说明文档

• 3.1.启动SpringBoot项目，访问：http://127.0.0.1:8080/swagger-ui.html
  

• 3.2.对接口进行测试

  • 3.2.1.找到想要测试接口,点击 Try out 按钮
    

  • 3.2.2.输入参数，点击Execute执行
    

  • 3.2.3.发送请求返回的响应结果
    

4.Swagger常用注解说明

• @API：请求类的说明 —> 用于controller类上
• @ApiOperation：方法的说明 —> 用于方法的上面
• @ApiImplicitParams：用在请求的方法上, 包含一组参数说明 —> 用于方法的上面
• @ApiImplicitParam：对单个参数的说明，包含以下属性
  • name：参数名
  • value：参数的汉字说明, 解释
  • required：参数是否必须传
  • paramType：参数放在哪个地方
  • dataType： 参数类型, 默认 String, 其它值 dataType="Integer”
  • defaultValue：参数的默认值
• @ApiResponses、@ApiResponse：进行方法返回值的说明
  • code：状态码，如200、400、401等
  • message：信息，例如"请求成功”
  • response：抛出异常的类

@RestController
@Api(tags = "用户管理模块" ,value = "该参数没什么意义, 所以不需要配置")
public class UserController{

	@Resource
    private UserDAO userDAO;

    @PostMapping("getUserInfo")
	@ApiOperation(value = "根据用户名获取用户信息接口")
	@ApiImplicitParams({
       	@ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String", paramType = "query", defaultValue = "Tony")
  		})
	@ApiResponses({
		@ApiResponse(code = 200, message = "成功"),
       	@ApiResponse(code = 500, message = "失败")
   	})
	public User getUserInfo(String userName){
			return userDAO.getUserInfo(userName);
	}
}

• @ApiModel：用在 JavaBean 类上，说明 JavaBean 的 用途
• @ApiModelProperty：用在 JavaBean 类的属性上面，说明此属性的的含议

@ApiModel(value = "User", description = "用户实体类")
public class User implements Serializable{
	@ApiModelProperty(value = "用户名")
	private String userName;
    @ApiModelProperty(value = "密码")
	private String passWord;
}

• @ApiIgnore：忽略某个接口，不生成在Swagger的接口说明文档中
• 整体结果展示

5.原始页面太丑，换个页面

• springfox-swagger-ui 的界面长这个样子，说实话，确实略显丑陋。
• 改成改良后的 Knife4j 不仅在界面上更加优雅、炫酷，功能上也更加强大：后端 Java 代码和前端 UI 模块分离了出来，在微服务场景下更加灵活；更提供了专注于 Swagger 的增强解决方案.

<!-- 将原来的springfox-swagger2版本改成3.0.0，解决以下版本兼容性问题 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

<!-- 将原来的springfox-swagger-ui版本改成knife4j-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

• 再来看一下效果，访问：http://127.0.0.1:8080/doc.html 是不是好了很多啊，完毕撒花