SpringBoot之Swagger2的使用

Posted 2021-02-02 小崔笔记本

Swagger是一组围绕OpenAPI规范构建的开源工具，可帮助设计、构建、记录和使用REST API。简单说下，它的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。

Swagger常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiParamImplicitL：一个请求参数
@ApiParamsImplicit 多个请求参数

集成Swagger

集成Swagger比较简单，这里是在之前章节demo的基础上做修改。首先引入Swagger相关依赖。

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

与启动类同级包建立Swagger2

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.ApiInfo;
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
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("社会主义接班人", "https://www.cnblogs.com/5ishare", "[e-mail]"))
                //版本号
                .version("1.0")
                //描述
                .description("用户管理")
                .build();
    }
}

在UserController中设置接口信息。

package com.example.demo;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.example.mapper.UserMapper;
import com.example.model.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/user")
public class UserController {
    
    @Autowired
    private UserMapper userMapper;
    
    @ApiOperation(value ="查询所有用户",notes ="",httpMethod = "GET")
    @GetMapping("/user")
    public List<User> userList(){
     return  userMapper.getAll();
    }
    
    /**
     * 查询用户根据id
     * @return USer对象
     * @param  id
     */
    @ApiOperation(value = "查询用户",notes = "根据用户id查询用户",httpMethod = "GET")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
    @GetMapping("/user/{id}")
    public User getUserById(@PathVariable String id){
        User user  = userMapper.getOne(id);
        return user;
    }
    /**
     * 新增User
     * @param user
     * @return success or error
     */
    @ApiOperation(value = "新增用户",notes = "",httpMethod = "POST")
    @ApiImplicitParam(name = "user",value = "用户实体",required = true,dataType = "User")
    @PostMapping("/user")
    public String createUser(@RequestBody User user){
       int num =  userMapper.insert(user);
       if(num>0){
           return "success";
       }
        return "error";
    }
    /**
     * 更新User
     * @param user
     * @return success or error
     */
    @ApiOperation(value = "更新用户",notes = "根据用户id更新用户",httpMethod = "PUT")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String"),
            @ApiImplicitParam(name = "user",value = "用户实体,传入更改后的数据",required = true,dataType = "User")
    })
    @PutMapping("user/{id}")
    public String updateUser(@PathVariable String id,@RequestBody User user){
       int num =  userMapper.update(user);
        if(num>0){
            return "success";
        }
        return "error";
    }

    /**
     * 删除用户
     * @param id
     * @return success or error
     */
    @ApiOperation(value = "删除用户",notes = "",httpMethod = "DELETE")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
   @DeleteMapping("user/{id}")
    public String deleteUser(@PathVariable String id){
        int num = userMapper.delete(id);
       if(num>0){
           return "success";
       }
        return "error";
    } 
}

在启动类设置@MapperScan

@MapperScan("com.example.mapper")

启动项目，在浏览器输入http://localhost:8080/swagger-ui.html，即可看到下面截图信息。

下图是项目的结构图。

参考：https://blog.csdn.net/qq_22860341/article/details/81119796