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

相关推荐
张人玉14 分钟前
C# 常量与变量
java·算法·c#
Java技术小馆28 分钟前
GitDiagram如何让你的GitHub项目可视化
java·后端·面试
Codebee44 分钟前
“自举开发“范式:OneCode如何用低代码重构自身工具链
java·人工智能·架构
星星电灯猴1 小时前
iOS 性能调试全流程:从 Demo 到产品化的小团队实战经验
后端
程序无bug1 小时前
手写Spring框架
java·后端
程序无bug1 小时前
Spring 面向切面编程AOP 详细讲解
java·前端
JohnYan1 小时前
模板+数据的文档生成技术方案设计和实现
javascript·后端·架构
全干engineer1 小时前
Spring Boot 实现主表+明细表 Excel 导出(EasyPOI 实战)
java·spring boot·后端·excel·easypoi·excel导出
Da_秀1 小时前
软件工程中耦合度
开发语言·后端·架构·软件工程
Fireworkitte1 小时前
Java 中导出包含多个 Sheet 的 Excel 文件
java·开发语言·excel