SpringBoot整合Swagger2

2023-11-17 18:03:19

1.概述

1.1定义

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。简单来说，它可以对API 自动生成在线文档，无需手动编写接口文档。另外其文档还支持在线测试，可直接对接口进行测试。

1.2注解

其主要依赖于注解，部分关键注解说明如下：

注解名称	说明
@Api	用在类上，说明该类的作用
@ApiModel	用在类上，表示对类进行说明，用于实体类中的参数接收说明
@ApiModelProperty	用于字段，表示对 model 属性的说明
@ApiOperation	用在Controller 里的方法上，说明方法的作用，每一个接口的定义
@ApiResponses、 @ApiResponse	@ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse
@ApiImplicitParam、 @ApiImplicitParams	@ApiImplicitParam用于方法上，为求参数进行说明；@ApiImplicitParams 组装了多个@ApiImplicitParam
@ApiIgnore	用于方法上，忽略某个接口文档

@ApiImplicitParam的具体说明如下：


name	参数名，对应方法中单独的参数名称
value	参数中文说明
required	是否必填。true必填，false非必填
dataType	参数数据类型
defaultValue	默认值
paramType	参数类型，取值为 path、query、body、header、form

2.实战演练

2.1环境准备

新建一个SpringBoot的项目，导入需要的依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

2.2接入Swagger2

第一步：导入依赖

      <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>

第二步：创建配置类。此配置类主要配置Swagger的相关信息，如api接口的所在包、文档说明等信息

package com.example.demo;

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).select()
                //配置apis要扫描的controlelr的位置
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                //配置路径
                .paths(PathSelectors.any())
                //构建文件的基本信息
                .build().apiInfo(
                        new ApiInfoBuilder().description("微微一笑接口测试文档")
                                .contact(new Contact("哈哈哈","https://github.com.lenve","1916008067@qq.com"))
                        .version("v1.1.0")
                        .title("API测试文档")
                        .build());
    }
}

第三步：创建用户实体

package com.example.demo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(value = "用户实体")
public class User {

    @ApiModelProperty(value = "id")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private  String username;

    @ApiModelProperty(value = "性别，0男，1女")
    private Integer sex;

}

第四步：创建开发接口，使用上述的注解

package com.example.demo.controller;

import com.example.demo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@Api(tags = "用户接口")//描述UserController的信息
public class UserController {
 
    @ApiOperation(value = "查询用户",notes = "根据id查询用户")
    @ApiImplicitParam(paramType = "path",name="id",value = "用户id",required = true)
    @GetMapping("/user/query/{id}")
    public String getUserById(@PathVariable Integer id) {
        return "/user/"+id;
    }

    @ApiResponses({
            @ApiResponse(code=200,message="删除成功"),
            @ApiResponse(code=500,message="删除失败")})
    @ApiOperation(value = "删除用户",notes = "根据id删除用户")
    @DeleteMapping("/user/delete/{id}")
    public Integer deleteUserById(@PathVariable Integer id) {
        return id;
    }

    @ApiOperation(value = "添加用户",notes = "添加一个用户，传入用户名和性别")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name="username",value = "用户名",required = true,defaultValue = "张三"),
            @ApiImplicitParam(paramType = "query",name="sex",value = "性别",required = true,defaultValue = "女")
    })
    @PostMapping("/user")
    public String addUser(@RequestParam String username,@RequestParam String sex){
        return username+","+sex;
    }

    @ApiOperation(value="修改用户",notes = "根据传入的用户信息修改用户")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user){
        return user.toString();
    }

    @GetMapping("/ignore")
    @ApiIgnore
    public void ignoreMethod(){}


}

第四步：测试。启动项目，在浏览器输入http://localhost:8080/swagger-ui.html就可以看到接口的信息

展开接口，就能看到所有的接口详细信息。以添加用户接口为例：

点击 try it out 按钮，可以对其进行接口的测试。

码农公寓