SpringBoot实战之一swagger

目录

1. 简介

2. springboot集成swagger

3. 配置swagger

4. swagger注解

4.1 controller 类下注解

4.1.1 请求类的注解

4.1.2 方法和输入参数的注解

4.1.3 返回参数或对象说明的注解

4.2 实体类下注解

4.2.1 实体类的注解

5. swagger测试

6.总结

---

1. 简介

swagger是什么？
1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

2. springboot集成swagger

在原有的springboot的项目中依赖pom下添加swagger的依赖：

    <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>

3. 配置swagger

在项目中引入swagger之后，需要编写对应的配置类，标注上@Configuration，@EnableSwagger2注解，并创建一个Docket对象。docket() 方法创建Docket的Bean对象，apiInfo()则是创建ApiInfo的基本信息。

下面代码一个模板：

import springfox.documentation.service.Contact;
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.Tag;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Description: swagger配置类
 * @date: 2022/10/4 13:54
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 添加标签
                .tags(new Tag("UserController", "用户服务"),
                        new Tag("LogController", "日志服务"))
                .select()
                // 扫描目的包路径
                .apis(RequestHandlerSelectors.basePackage("com.workhard.curd.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("MyBatis CURD操作")
                //创建人
                .contact(new Contact("阿肯色人", "https://www.baidu.com", "aaabbb@mail.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

然后重启项目，访问swagger页面地址：http://llocalhost:端口号/swagger-ui.html

4. swagger注解

在代码中swagger是以注解的形式使用，下面对其进行介绍：

4.1 controller 类下注解

4.1.1 请求类的注解

注解	说明
@Api	对请求类的说明

规范：

@API: 放在 请求的类上, 与 @Controller 并列, 说明类的作用。

@API属性配置: 

属性名称	备注
value	url 的路径值
tags	如果设置这个值、value 的值会被覆盖
description	对 api 资源的描述
basePath	基本路径

示例:

@RequestMapping("/log")
@Api(tags = {"LogController"})
public class LogController {
...
}

4.1.2 方法和输入参数的注解

注解	说明
@ApiOperation	方法的说明
@ApiImplicitParams @ApiImplicitParam	方法的参数的说明； @ApiImplicitParams 用于指定单个参数的说明

@ApiOperation属性配置

@ApiImplicitParam属性配置

属性名称	备注
name	参数的汉字说明, 解释
value	参数是否必须传
required	基本路径
dataType:	参数类型, 默认 String, 其它值dataType=“Integer”
defaultValue	参数的默认值

示例:

    @ApiOperation(value = "根据ID查找日志记录", notes="根据ID查找日志记录")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "日志ID", paramType = "path", required = true, dataType = "Integer")
    })
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public LogExtend logExtend(@PathVariable int id){
        return logService.selExtend(id);
    }

4.1.3 返回参数或对象说明的注解

注解	说明
@ApiResponses	方法返回值的说明
@ApiResponse	用于指定单个参数的说明

 @ApiResponse属性配置

属性名称	备注
code	返回值编码, 例如 400
message	返回信息
response	抛出异常的类

 完整示例：

/**
 * @Description: log相关的web接口
 * @date: 2022/10/4 12:31
 */
@RestController
@RequestMapping("/log")
@Api(tags = {"LogController"})
public class LogController {
    @Autowired
    private LogService logService;


    @ApiOperation(value = "根据ID查找日志记录", notes="根据ID查找日志记录")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "日志ID", paramType = "path", required = true, dataType = "Integer")
    })
    @ApiResponses({
            @ApiResponse(code = 400, message = "配置参数有误，请检查！"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对！")
    })
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public LogExtend logExtend(@PathVariable int id){
        return logService.selExtend(id);
    }

    @ApiOperation(value = "新增日志记录", notes="新增日志记录")
    @RequestMapping(value = "/insertwithfields",method = RequestMethod.PUT)
    public Log create(@RequestBody Log log) {
        return logService.insertWithFields(log);
    }
}

4.2 实体类下注解

4.2.1 实体类的注解

注解	说明
@ApiModel	用在 JavaBean 类上，说明 JavaBean 的 用途
@ApiModelProperty	用在 JavaBean 类的属性上面，说明此属性的的含义

​​​​​​​

示例：

/**
 * @Description: 实体类
 * @date: 2022/9/4 8:24
 */
@ApiModel(description = "日志实体类")
public class Log {
    @ApiModelProperty(value = "日志ID")
    private Integer id;

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

    @ApiModelProperty(value = "日志内容")
    private String action;

    @ApiModelProperty(value = "创建时间")
    private Date createTime;

    ...
}

5. swagger测试

本节以MyBatis CRUD下的LogController控制类的log接口进行测试。

点击测试 

输入这个请求需要的参数，并执行

可以看到各种信息及其返回数据格式

6.总结

本文简要对swagger进行了介绍，并介绍了如何在springboot项目中集成swagger，swagger是优秀的api文档工具，对于它的其他使用后续在使用中进一步补充。