SpringBoot 集成 Swagger

最新推荐文章于 2025-03-22 00:41:12 发布

Alan丶K

最新推荐文章于 2025-03-22 00:41:12 发布

阅读量175

点赞数

文章标签： java spring spring boot

本文链接：https://blog.youkuaiyun.com/xyzx123456/article/details/117299078

版权

一.Swagger是什么：

根据官网的介绍：

Swagger Inspector：测试API和生成OpenAPI的开发工具。Swagger Inspector的建立是为了解决开发者的三个主要目标。

1、执行简单的API测试

2、生成OpenAPI文档

3、探索新的API功能

二.Swagger有几个优点以及我的理解：

我的理解Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。简单来说，Swagger是一个功能强大的接口管理工具，并且提供了多种编程语言的前后端分离解决方案。根据我的使用，当然我只是最简单的使用，我感觉Swagger有以下几个优点：

1、Swagger可以整合到代码中，在开发时通过注解，编写注释，自动生成API文档。

2、将前端后台分开，不会有过分的依赖。

3、界面清晰，无论是editor的实时展示还是ui的展示都十分人性化，如果自己仅仅用markdown来编写，又要纠结该如何展现，十分痛苦。

三.Springboot集成Swagger的几个步骤

(1):Swagger的配置文件



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

/**
 * Swagger 配置文件
 */
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.two"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot利用Swagger构建API文档")
                .description("使用RestFul风格, 创建人：Alan丶K")
                .termsOfServiceUrl("https://github.com/cicadasmile")
                .version("version 1.0")
                .build();
    }
}

(1):实体类的配置

@Data
@Accessors(chain = true)
@TableName("t_jtd_base_bank")
@ApiModel(value="BankEntity对象", description="银行 ")
public class BankEntity extends BaseLogicDelEntity {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "银行id")
    @JsonSerialize(using = ToStringSerializer.class)
    @TableId(value = "bank_id", type = IdType.AUTO)
    private Long bankId;

    @ApiModelProperty(value = "行号")
    private String bankCode;

    @ApiModelProperty(value = "行名")
    private String bankName;

    @ApiModelProperty(value = "清算行")
    private String bankClear;

    @ApiModelProperty(value = "状态(1:正常;2:注销)")
    private String status;

}

(3):Controller的配置



import com.swagger.two.entity.JsonResult;
import com.swagger.two.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import java.util.*;

/**
 * Rest风格用户的增删改查接口
 * Swagger2 注解整理
 * ====================================================
 * ====================================================
 * 
 * 
 */
@RestController
@Api(tags = "用户接口",description="用户文档说明",hidden=true)
public class UserController {
    // 创建线程安全的Map
    static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());

    /**
     * 添加用户
     */
    @ApiOperation(value="添加用户", notes="创建新用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value = "/addUser", method = RequestMethod.POST)
    public ResponseEntity<JsonResult> addUser (@RequestBody User user){
        JsonResult result = new JsonResult();
        try {
            users.put(user.getId(), user);
            result.setResult(user.getId());
            result.setStatus("ok");
        } catch (Exception e) {
            result.setResult("服务异常");
            result.setStatus("500");
            e.printStackTrace();
        }
        return ResponseEntity.ok(result);
    }

    /**
     * 根据ID查询用户
     */
    @ApiOperation(value="用户查询", notes="根据ID查询用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "/getUserById/{id}", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
        JsonResult result = new JsonResult();
        try {
            User user = users.get(id);
            result.setResult(user);
            result.setStatus("200");
        } catch (Exception e) {
            result.setResult("服务异常");
            result.setStatus("500");
            e.printStackTrace();
        }
        return ResponseEntity.ok(result);
    }

    /**
     * 查询用户列表
     */
    @ApiOperation(value="用户列表", notes="查询用户列表")
    @RequestMapping(value = "/getUserList", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserList (){
        JsonResult result = new JsonResult();
        try {
            List<User> userList = new ArrayList<>(users.values());
            result.setResult(userList);
            result.setStatus("200");
        } catch (Exception e) {
            result.setResult("服务异常");
            result.setStatus("500");
            e.printStackTrace();
        }
        return ResponseEntity.ok(result);
    }

    /**
     * 根据ID修改用户信息
     */
    @ApiOperation(value="更新用户", notes="根据Id更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户对象user", required = true, dataType = "User")
    })
    @RequestMapping(value = "/updateById/{id}", method = RequestMethod.PUT)
    public ResponseEntity<JsonResult> updateById (@PathVariable("id") Integer id, @RequestBody User user){
        JsonResult result = new JsonResult();
        try {
            User user1 = users.get(id);
            user1.setUsername(user.getUsername());
            user1.setAge(user.getAge());
            users.put(id, user1);
            result.setResult(user1);
            result.setStatus("ok");
        } catch (Exception e) {
            result.setResult("服务异常");
            result.setStatus("500");
            e.printStackTrace();
        }
        return ResponseEntity.ok(result);
    }

    /**
     * 根据id删除用户
     */
    @ApiOperation(value="删除用户", notes="根据id删除指定用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value = "/deleteById/{id}", method = RequestMethod.DELETE)
    public ResponseEntity<JsonResult> deleteById (@PathVariable(value = "id") Integer id){
        JsonResult result = new JsonResult();
        try {
            users.remove(id);
            result.setResult(id);
            result.setStatus("ok");
        } catch (Exception e) {
            result.setResult("服务异常");
            result.setStatus("500");
            e.printStackTrace();
        }
        return ResponseEntity.ok(result);
    }

    @ApiIgnore//使用该注解忽略这个API
    @RequestMapping(value = "/ignoreApi", method = RequestMethod.GET)
    public String  ignoreApi() {
        return "Spring Boot Swagger !";
    }
}

(4):每个注解的含义：

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