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

相关推荐
一只叫煤球的猫8 小时前
写代码很6,面试秒变菜鸟?不卖课,面试官视角走心探讨
前端·后端·面试
bobz9658 小时前
tcp/ip 中的多路复用
后端
bobz9658 小时前
tls ingress 简单记录
后端
皮皮林5519 小时前
IDEA 源码阅读利器,你居然还不会?
java·intellij idea
你的人类朋友9 小时前
什么是OpenSSL
后端·安全·程序员
bobz96510 小时前
mcp 直接操作浏览器
后端
前端小张同学12 小时前
服务器部署 gitlab 占用空间太大怎么办,优化思路。
后端
databook12 小时前
Manim实现闪光轨迹特效
后端·python·动效
武子康13 小时前
大数据-98 Spark 从 DStream 到 Structured Streaming:Spark 实时计算的演进
大数据·后端·spark
该用户已不存在13 小时前
6个值得收藏的.NET ORM 框架
前端·后端·.net