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 导入依赖

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

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

相关推荐
paopaokaka_luck1 分钟前
智能推荐社交分享小程序(websocket即时通讯、协同过滤算法、时间衰减因子模型、热度得分算法)
数据库·vue.js·spring boot·后端·websocket·小程序
留不住丨晚霞9 分钟前
说说SpringBoot常用的注解?
java·开发语言
华科云商xiao徐15 分钟前
Java多线程爬虫动态线程管理实现
java·爬虫·数据挖掘
程序员NEO17 分钟前
Spring AI 对话记忆大揭秘:服务器重启,聊天记录不再丢失!
人工智能·后端
用户214118326360217 分钟前
惊爆!国内轻松白嫖 Claude Code,编程效率狂飙
后端
iccb101323 分钟前
我是如何实现在线客服系统的极致稳定性与安全性的
前端·javascript·后端
柒七爱吃麻辣烫24 分钟前
八股文系列-----SpringBoot自动配置的流程
java·spring boot·rpc
M1A129 分钟前
Java 面试系列第一弹:基础问题大盘点
java·后端·mysql
发仔12329 分钟前
Dubbo介绍及示例用法
java·dubbo
goxingman37 分钟前
关于使用idea打包的时候报错,Maven提示乱码java: �Ҳ�������
java·maven·intellij-idea