【接口篇】SpringBoot 整合 Swagger2 实现在线 API 文档

·  阅读 208

写在最前

前后端分离是目前一种非常流行的开发模式,前端和后端开发人员通过 接口文档 进行接口对接,它使项目的分工更加明确:

image-20220414110655830

后端在编写接口同时需要维护接口文档,前端经常抱怨后端给的接口文档与实际情况不一致,因为接口可能修改了,但是文档没有及时更新。无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档(能及时更新的接口文档)。为解决这些问题,Swagger 诞生了!

什么是 Swagger

Swagger 是一个开源软件框架,可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务,它将代码和文档融为一体,可以完美解决文档编写繁琐、维护不方便等问题。使得开发人员可以将大部分精力集中到业务中,而不是繁杂琐碎的文档中。

Spring + Swagger 配合注解即可完成接口文档的自动编写(接口文档与实际情况始终一致),同时也无需借助第三方工具,如 Postman 来测试接口,直接通过 Swagger 提供的工具测试接口。

SpringBoot 整合 Swagger2

1.引入 Swagger2 依赖

<!--  swagger2  -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
复制代码

2.编写 Swagger 配置文件

import java.util.ArrayList;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

/**
 * Swagger 配置
 *
 * @author : Strive
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

  /** 配置 Swagger 2 注册一个 Bean 属性 enable():是否启用 Swagger,启用后才能在浏览器中进行访问 groupName():用于配置 API 文档的分组 */
  @Bean
  public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(true)
        .groupName("v2")
        .select()
        // 过滤路径
        .paths(PathSelectors.any())
        // 指定扫描的包
        .apis(RequestHandlerSelectors.basePackage("com.csp.mingyue.swagger.controller"))
        .build();
  }

  private ApiInfo apiInfo() {
    /*作者信息*/
    Contact contact =
        new Contact(
            "Strive", "https://gitee.com/csps/mingyue-springboot-learning", "732171109@qq.com");
    return new ApiInfo(
        "Swagger 测试接口文档",
        "【接口篇】SpringBoot 快速实践 RESTful API 架构风格",
        "v2.0",
        "https://gitee.com/csps/mingyue-springboot-learning",
        contact,
        "Apache 2.0",
        "http://www.apache.org/licenses/LICENSE-2.0",
        new ArrayList());
  }
}
复制代码

3.编写接口

  • controller

    import com.csp.mingyue.swagger.model.MingYueUser;
    import com.csp.mingyue.swagger.service.MingYueUserService;
    import io.swagger.annotations.Api;
    import lombok.RequiredArgsConstructor;
    import org.springframework.http.ResponseEntity;
    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;
    
    /** @author Strive */
    @Api(tags = "用户模块")
    @RestController
    @RequiredArgsConstructor
    @RequestMapping("/user")
    public class MingYueUserController {
    
      private final MingYueUserService mingYueUserService;
    
      @GetMapping("/{userId}")
      public ResponseEntity<MingYueUser> queryUserById(@PathVariable Long userId) {
        return ResponseEntity.ok(mingYueUserService.queryUserById(userId));
      }
    
      @PostMapping
      public ResponseEntity<Long> addUser(@RequestBody MingYueUser user) {
        return ResponseEntity.ok(mingYueUserService.addUser(user));
      }
    
      @PutMapping
      public ResponseEntity<String> updateUser(@RequestBody MingYueUser user) {
        return ResponseEntity.ok(mingYueUserService.updateUser(user));
      }
    
      @DeleteMapping("/{userId}")
      public ResponseEntity<String> deleteUser(@PathVariable Long userId) {
        return ResponseEntity.ok(mingYueUserService.deleteUser(userId));
      }
    }
    复制代码
  • service

    import cn.hutool.core.map.MapUtil;
    import com.csp.mingyue.swagger.model.MingYueUser;
    import java.util.Map;
    import org.springframework.stereotype.Service;
    
    /** @author Strive */
    @Service
    public class MingYueUserService {
    
      /** 模拟用户存储 */
      private static final Map<Long, MingYueUser> USER_MAP = MapUtil.newHashMap();
    
      static {
        USER_MAP.put(1L, MingYueUser.builder().userId(1L).username("mingyue").build());
      }
    
      /**
       * 根据用户ID查询用户信息
       *
       * @param userId 用户ID
       * @return 用户信息
       */
      public MingYueUser queryUserById(Long userId) {
        return USER_MAP.get(userId);
      }
    
      /**
       * 添加用户
       *
       * @param user 用户信息
       * @return 新用户ID
       */
      public Long addUser(MingYueUser user) {
        USER_MAP.put(2L, user);
    
        return user.getUserId();
      }
    
      /**
       * 更新用户
       *
       * @param user 用户信息
       */
      public String updateUser(MingYueUser user) {
        MingYueUser mingYueUser = USER_MAP.get(user.getUserId());
    
        USER_MAP.put(user.getUserId(), user);
    
        return mingYueUser.getUsername() + " 更新为:" + user.getUsername();
      }
    
      /**
       * 根据用户ID删除用户
       *
       * @param userId 用户ID
       */
      public String deleteUser(Long userId) {
        int size = USER_MAP.size();
    
        USER_MAP.remove(userId);
    
        return "原" + size + "用户,删除后还有" + USER_MAP.size();
      }
    }
    复制代码
  • model

    import io.swagger.annotations.ApiModelProperty;
    import lombok.AllArgsConstructor;
    import lombok.Builder;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    import lombok.ToString;
    
    /** @author Strive */
    @Data
    @ToString
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @ApiModel(value = "用户实体类", description = "用户信息描述类")
    public class MingYueUser {
    
      @ApiModelProperty(value = "用户id")
      private Long userId;
    
      @ApiModelProperty(value = "用户名")
      private String username;
    }
    复制代码

4.启动项目

访问:http://localhost:8080/swagger-ui.html

image-20220414193543981

5.测试接口

image-20220414194514489

Demo 地址

mingyue-springboot-swagger2

分类:
后端
标签:
分类:
后端
标签:
收藏成功!
已添加到「」, 点击更改