526互联

swagger

发布时间 2023-07-24 20:34:38作者: 回眸晓三生

springboot 集成 Swagger在线接口文档

1、swagger简介

2、swagger的maven依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

3、swagger配置

Spring Boot 中对 Swagger 的配置非常方便，
新建一个配置类，
类上除了添加必要的@Configuration 注解外，
还需要添加@EnableOpenApi 注解

package com.li.conf;

import io.swagger.models.HttpMethod;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@EnableOpenApi//启用OpenAPI（以前称为Swagger）自动生成的API文档。
@Configuration
public class Swagger3Config {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * swagger测试地址：http://localhost:8080/swagger-ui/index.html#/
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 使用Swagger3.0版本
                .enable(true)// 是否关闭在线文档，生产环境关闭
                .apiInfo(apiInfo())  // 指定构建api文档的详细信息的方法
                .select()  // 指定要生成api接口的包路径，这里把action作为包路径，生成controller中的所有接口
                 .apis(RequestHandlerSelectors.basePackage("com.yan.action"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))方法接口上添加了ApiOperation注解
                .paths(PathSelectors.any()).build()
                //针对应用的全局响应消息配置
//                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
//                .globalResponses(HttpMethod.POST, getGlobalResponseMessage())
                ;
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档") //设置页面标题
                .description("说明信息")  //设置接口描述
                .contact(new Contact("li", "http://baidu.com", "li@li.com")) //设置联系方式
                .version("1.0") //设置版本
                .build();  //构建
    }
}

4、swagger的使用

Swagger中常用的注解，分别在实体类上、Controller 类上以及 Controller 中的方法上。

4.1 实体类注解

实体类的注解主要介有：@ApiModel 和@ApiModelProperty 注解。

  • @ApiModel 注解用于实体类，表示对类进行说明，用于参数用实体类接收。
@ApiModel(value = "用户实体类")
public class User {}
  • @ApiModelProperty 注解用于类中属性，表示对 model 属性的说明或者数据操作更改
public class User {
    @ApiModelProperty(value = "用户唯一标识")
    private Long id;
    @ApiModelProperty(value = "用户姓名")
    private String username;
    @ApiModelProperty(value = "用户密码")
    private String password;
}

User类：

@ApiModel(value = "用户实体类")
public class User {
    @ApiModelProperty(value = "用户唯一标识")
    private Long id;
    @ApiModelProperty(value = "用户姓名")
    private String username;
    @ApiModelProperty(value = "用户密码")
    private String password;
}

4.2 Controller类注解

Controller类注解主要介有：@Api、@ApiOperation、@ApiParam

  • 1、@Api 注解用于类上，表示标识这个类是 swagger 的资源。
@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController{}
  • 2、@ApiOperation 注解用于方法
public class TestController {
@GetMapping("/get/{id}")
@ApiOperation(value = "根据用户唯一标识获取用户信息",notes = "用户测试notes",tags = "角色管理")
public JsonResult<User> getUserInfo(Long id) {}
}

value：可以当作是接口的简称
notes：接口的描述
tags：可以额外定义接口组，比如这个接口外层已经有@Api(tags = "用户管理")，将接口划分到了“用户管理”中，但你可以额外的使用tags，例如tags = "角色管理"让角色管理中也有这个接口文档。

  • 3、@ApiParam 注解用于参数上，用来标明参数信息。
public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
// 模拟数据库中根据 id 获取 User 信息
User user = new User(id, "李骏瑞", "123456");
return new JsonResult(user);
}

Controller类

@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {
@GetMapping("/get/{id}")
@ApiOperation(value = "根据用户唯一标识获取用户信息")
public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
// 模拟数据库中根据 id 获取 User 信息
User user = new User(id, "李骏瑞", "123456");
return new JsonResult(user);
}
}