SpringBoot之Swagger2的使用

时间：2022-07-02 23:10:39

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", "991843897@qq.com"))

                //版本号

                .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，即可看到下面截图信息。

SpringBoot之Swagger2的使用

下图是项目的结构图。

SpringBoot之Swagger2的使用

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

相关文章