SpringBoot整合Swagger2

SpringBoot整合Swagger2

  • 1.什么是Swagger2?(应用场景)
  • 2.项目中如何使用
    • [2.1 导入依赖](#2.1 导入依赖)
    • [2.2 编写配置类](#2.2 编写配置类)
    • [2.3 注解使用](#2.3 注解使用)
      • [2.3.1 controller注解:](#2.3.1 controller注解:)
      • [2.3.2 方法注解](#2.3.2 方法注解)
      • [2.3.3 实体类注解](#2.3.3 实体类注解)
      • [2.3.4 方法返回值注解](#2.3.4 方法返回值注解)
      • [2.3.5 忽略的方法](#2.3.5 忽略的方法)
  • 3.UI界面

1.什么是Swagger2?(应用场景)

Swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

进一步说,这个接口文档就是写给前端用的。有时候后端可能会忘记编写接口文件,那么Swagger2就帮后端开发者写。

2.项目中如何使用

2.1 导入依赖

这里导入了两个依赖包,第二个依赖包主要是访问swagger2的UI界面

xml 复制代码
    <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.2 编写配置类

这个配置类的写法比较固定,其中getApiInfo()方法主要设置接口文档的一些信息,包括标题、描述以及版本等。api()这个Bean写法比较固定,其中basePackage中的地址不必要搞错,针对于不同接口,更换不同地址。

java 复制代码
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rql.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo(){
        Contact contact = new Contact("name", "https://blog.csdn.net/qq_42569028?type=blog", "1476804025@qq.com");
        return new ApiInfoBuilder()
                .title("标题:图书管理系统")
                .description("描述:对图书进行增删改查操作")
                .version("版本:项目版本V1.0")
                .contact(contact)
                .build();

    }
}

2.3 注解使用

2.3.1 controller注解:

@Api:修饰整个类,描述Controller的作用
tags:"说明该类的作用"

java 复制代码
@RestController
@RequestMapping("/books")
@Api(tags = "图书管理系统")
public class BookController {

2.3.2 方法注解

@ApiOperation:对类中的方法进行描述

  • value="说明方法的作用"

  • notes="方法的备注说明"

@ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
@ApiImplicitParam :描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值

txt 复制代码
    name:参数名
    value:参数的汉字说明、解释
    required:参数是否必须传
    dataType :参数类型,默认String,其它值dataType="int"
    defaultValue:参数的默认值
    paramType:参数放在哪个地方
        header --> 请求参数的获取:@RequestHeader
        query --> 请求参数的获取:@RequestParam
        path(用于restful接口)--> 请求参数的获取:@PathVariable
        body(请求体)--> @RequestBody User user
        form(普通表单提交)
java 复制代码
    @GetMapping("{pageNo}/{pageSize}")
    @ApiOperation("分页查询数据信息")
    @ApiImplicitParams(
            {@ApiImplicitParam(name = "pageNo",value = "当前所在的页数"),
            @ApiImplicitParam(name = "pageSize",value = "分页的大小"),
            @ApiImplicitParam(name = "book",value = "书籍信息")
            })
    public R getPages(@PathVariable Integer pageNo, @PathVariable Integer pageSize,Book book){

2.3.3 实体类注解

@ApiModel:用对象来接收参数时,用于描述对象(实体类中的注解)

(这种一般用在post创建的时候,使用 @RequestBody 这样的场景,请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )

@ApiProperty:用对象接收参数时,描述对象的一个字段(实体类中属性的注解)

java 复制代码
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description = "书籍信息")
public class Book {

    private Integer id;
    @ApiModelProperty(value = "书籍类型")
    private String type;
    @ApiModelProperty(value = "书籍名称")
    private String name;
    @ApiModelProperty(value = "书籍描述")
    private String description;
    private Integer deleted;
}

2.3.4 方法返回值注解

@ApiResponses:方法返回对象的说明
@ApiResponse:每个参数的说明
code:数字,例如400
message:信息,例如"请求参数没填好"

java 复制代码
@ApiResponses({
            @ApiResponse(code = 200,message = "成功获取书籍信息"),
            @ApiResponse(code=400,message = "查询逻辑有问题")
    })
    public R getById(@PathVariable Integer id){
        return new R(true,bookService.getById(id));
    }

2.3.5 忽略的方法

@ApiIgnore:接口方法注解,添加此注解的方法将不会生成到接口文档中

3.UI界面

访问地址:http://localhost:8081/swagger-ui.html

相关推荐
tong_li4 分钟前
给娃做个 AI 陪写作业助手:LangChain4j 入门(三):配本古诗书(RAG 入门),答得不瞎编
后端
用户486789525339030 分钟前
多租户第二集:读隔离做完之后,写路径才是真坑
后端
Flynn Liang33 分钟前
Java 序列化也能成为瓶颈:Jackson、Protobuf 与 Redis 序列化的生产实践
java·redis·性能优化·jackson·序列化·protobuf
Yeats_Liao37 分钟前
物联网平台优化系列(三):全局懒加载吞掉 MQTT 初始化
java·物联网·struts
bai27337 分钟前
同一个 1.005,toFixed 给 1.00、Math.round 给 1、Intl 给 1.01:999 个三分位小数的实测
javascript·后端
千寻技术帮41 分钟前
基于Spring Boot+Vue的农产品销售管理系统(源码+文档+数据库,附部署教程)
java·数据库·spring boot·后端·mysql·vue
好用斋1 小时前
拾光坞G2使用新版Docker懒人包:一键安装、一键升级、一键卸载
java·docker·容器
码云社区1 小时前
Spring Boot陪诊陪护系统源码:医院目录、服务项目与城市业务配置
java·spring boot·后端·陪诊陪护·医院陪诊·医院陪护·陪护小程序
码云社区1 小时前
Spring Boot云快充协议源码:充电桩远程重启、参数配置与升级运维方案
运维·spring boot·后端·充电桩·充电系统·充电软件
Csvn2 小时前
Nginx 日志、监控与排障:全字段日志、条件日志与证据链定位
后端·nginx