SpringBoot———Swagger

---

一、概念

• 定义：Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

与postmane区别

• Swagger：用于自动生成接口文档
• Postman：用于调用、测试和调试接口

总结：最好养成写Swagger的习惯，因为Postman中的测试数据可能会丢失，但写在代码里的Swagger永远不会丢。

二、实现步骤

案例一：修改Swagger页面信息

1. 创建SpringBoot项目，导入swagger，ui依赖

<!--Swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--Swagger-ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. 编写SwaggerConfig配置类

@Configuration
@EnableSwagger2    // 开启Swagger2自动配置
public class SwaggerConfig {
}

结果：访问http://localhost:8080/swagger-ui.html路径可看到swagger自带页面

3. 自定义页面信息

Swagger实例Bean是Docket，通过配置Docket配置Swagger

@Configuration
@EnableSwagger2    // 开启Swagger2自动配置
public class SwaggerConfig {
    // 装配docket
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    // 配置页面信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("ZY", "https://blog.csdn.net/qq_45673367", "15929464574@163.com");
        return new ApiInfo(
                "ZY的Swagger学习之路", // 标题
                "让我们一起开始学习如何配置Swagger吧", // 描述
                "v1.0", // 版本
                "https://blog.csdn.net/qq_45673367/组织链接", // 学习链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

案例二：配置扫描包等信息

// 装配docket
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false) // 配置Swagger是否启用，默认true启用
                .select()  // 通过RequestHandlerSelectors配置扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.zy.controller"))
                .build();
    }

若配置是否启用为false，则网页不能访问

配置多个Docket

// 装配多个Docket
    @Bean
    public Docket docket01(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("默认");
    }

    // 装配多个Docket
    @Bean
    public Docket docket02(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("未知用户");
    }

    // 装配docket
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("zy") ...
    }

案例三：配置实体类

1. 编写实体类

注意：属性为public，这样才能被映射到Model中

@ApiModel("实体用户")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String pwd;
}

2. 配置controller

只要实体在请求接口的返回值上，都能被映射到实体Model中

@RequestMapping("/user")
    public User user(){
        return new User();
    }

• @ApiModel(“实体用户”)————类上的注释
• @ApiModelProperty(“用户名”)——————属性上的注释

三、 常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

1. @Api(tags = “controller类上”) ————作用在controller类上，表示这是一个Swagger的资源
2. @ApiOperation(“接口注解”) ————作用在接口方法上（controller请求上）
3. @ApiModel(“类注解”) ————作用在pojo实体类上
4. @ApiModelProperty(“属性注解”) ————作用在类方法和属性上，hidden设置为true可以隐藏该属性
5. @ApiParam(“参数注解”) ————作用在参数、方法和字段上（controller请求的参数上）

@Api(tags = "ZY的controller类")
@RestController
public class helloController {
    @GetMapping("/hello")
    public String hello(){
        return "hello,Swagger";
    }

    @PostMapping("/user")
    public User user(){
        return new User();
    }

    @GetMapping("/getName")
    @ApiOperation("获取用户名")  // 请求的注解
    public String getUsername(@ApiParam("用户名") String username){
        return "hello"+username;
    }

结果为：

四、生成测试文档（重要！！！）

主要功能：生成测试文档，可测试接口

@PostMapping("/postdemo")
    @ApiOperation("post测试")  // 请求的注解
    public User postDemo(User user){
        return user;
    }

1. 点击Try it out测试接口功能
   
2. 没有参数时，直接点击Execute执行
   
3. 返回正确的结果，显示200
   
   同时显示状态码对应的信息