当前位置: 首页 > biancheng >正文

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属性配置: 

属性名称备注
valueurl 的路径值
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文档工具,对于它的其他使用后续在使用中进一步补充。

相关文章:

  • 牛客练习赛#84 F 莫比乌斯反演+杜教筛+技巧+斐波那契数列和gcd的结论+矩阵快速幂
  • ZZNUOJ_用C语言编写程序实现1342:支配值数目(附完整源码)
  • java毕业设计后勤管理系统餐饮评价监督系统(附源码、数据库)
  • 前端基础学习笔记
  • 【TS】联合类型--类型断言--类型推断
  • 谈笑风声的秘密
  • QT影城网上售票系统
  • NetCDF数据在ArcMap中的使用
  • 打怪升级(考验思路)
  • 持续精进,改变自己