Swagger

最新推荐文章于 2025-04-24 10:26:30 发布

小熊哦呜

最新推荐文章于 2025-04-24 10:26:30 发布

阅读量1.8k

点赞数 20

文章标签： java python 算法

本文链接：https://blog.youkuaiyun.com/m0_70812512/article/details/143491770

版权

Swagger的简介

目前大部分的项目都是前后端分离的，后端除了要提供接口外，还需要提供接口文档，有时由于需求、设计或方案的变更，会造成接口变更但是接口文档没有及时更新的情况。Swagger是一个在你写接口的时候帮你自动生成接口文档，并且文档会随着接口的变化而变化的东西，只要你遵循它的规范并写一些接口的说明注解即可。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务的接口文档。下面我们通过一个实例来看一下Swagger的使用。

Swagger的使用

1. 添加依赖包

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

2. 配置Swagger

创建Swagger配置类：

// 标明是配置类
@Configuration
// 开启Swagger功能
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 构建一个Docket Bean
     * @return
     */
    @Bean
    public Docket createRestapi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 页面展示信息
                .apiInfo(apiInfo())
                // 返回一个ApiSelectorBuilder实例，用来控制接口被Swagger做成文档
                .select()
                // 用于指定扫描哪个包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                // 选择所有的API，如果你只想为部分API生成文档，可以配置这里
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 定义api文档主页面的基本信息
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("Swagger test")
                .description("API描述")
                // 版本号
                .version("1.0")
                .build();
    }

}

3. 创建User实体类

@ApiModel: 用来标注实体类，常用配置项：

value: model的别名，默认为类名
description: model的详细描述

@ApiModelProperty: 用来标注实体类的字段，常用配置项：

value: 字段说明
example: 字段的示例值
required: 是否为必填项

@Data
@ApiModel(description = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户id")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String name;

}

4. 创建测试类和方法

@Api: 用在类上，该注解将一个Controller（Class）标注为一个Swagger资源（API），常用配置项：

tags: API分组标签，具有相同标签的API将会被归并在一组内展示
value: 如果tags没有定义，value将作为Api的tags使用

@ApiOperation: 用来描述接口，常用配置项：

value: 接口的简单说明
notes: 接口的详细说明

@ApiParam: 接口参数的说明，常用配置项：

required: 是否必填，默认为false
value: 参数说明

@RestController
@RequestMapping("user")
@Api(tags = "用户管理")
public class UserController {

    @GetMapping("get")
    @ApiOperation(value = "获取用户信息")
    public User get(@ApiParam(value = "用户id", required = true) @RequestParam Integer id) {
        User user = new User();
        user.setId(id);
        user.setName("张三");
        return user;
    }

}

5. 访问host+swagger-ui.html

可点开用户管理和Models查看更详细的接口信息：

Swagger UI增强

swagger-bootstrap-ui是springfox-swagger的增强UI实现，这个ui的api文档结构更加清晰，在线调试也很方便。

增加以下依赖：

<dependency> 
    <groupId>com.github.xiaoymin</groupId> 
    <artifactId>swagger-bootstrap-ui</artifactId> 
    <version>1.9.6</version> 
</dependency>

增加swagger-bootstrap-ui依赖后，访问host+doc.html，页面展示如下：

分组

@Configuration
@EnableSwagger2
public class SwaggerConfig {


    //设置显示状态，value是在pom中配置的
    @Value("${zmall.swagger:false}")
    private boolean swaggerShow;

    @Bean
    public Docket createRestApiForAll() {
        return new Docket(DocumentationType.SWAGGER_2).enable(swaggerShow).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.zking.ssm.controller"))
                .paths(PathSelectors.any()).build().groupName("所有api").pathMapping("/");
    }

    //根据包进行分组

    @Bean
    public Docket createRestApiForAuth() {
        return new Docket(DocumentationType.SWAGGER_2).enable(swaggerShow).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.zking.ssm.controller.auth"))
                .paths(PathSelectors.any()).build().groupName("用户管理").pathMapping("/");
    }

    @Bean
    public Docket createRestApiForCs() {
        return new Docket(DocumentationType.SWAGGER_2).enable(swaggerShow).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.zking.ssm.controller.cs"))
                .paths(PathSelectors.any()).build().groupName("客户满意度").pathMapping("/");
    }

    // 按照路径进行分组
    @Bean
    public Docket web_api_admin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/api/admin/**"))
                .build()
                .groupName("系统管理员")
                .pathMapping("/");
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("zmall").description("电商项目").version("1.0.0").build();
    }
}