SpringBoot 整合 Swagger3_spring boot3的swagger

目录

一 为什么需要 swagger

二 swagger 是什么

三 swagger 集成

3.1 引入依赖

3.2 swagger 配置

3.3 Restful 接口

3.4 Swagger3 文档

四 swagger 注解说明

---

一 为什么需要 swagger

        目前前后端分离是一个业内趋势，那前后端接口协议，可以记录在 wiki 或者 gitlab 上， 但是记录在 wiki 或者 gitlab 那块手写接口文档很容易出现如下情况：

       1 需求的不断叠加，后端需要定期的更新文档，更新完了之后需要同步给客户端或者前端，很费劲。

       2 不能直接测试接口，通常需要使用工具，比如 postman；或者通过 curl 命令，门槛较高，麻烦。

       3 如果一个项目中的接口太多，维护都是一个成本很高的问题。

       swagger 就能完美的解决上述三个问题，但是 Swagger 的代码侵入性太强。

       为了解决上述问题，swagger 出现了。

二 swagger 是什么

       swagger 是一个自动生成接口文档的工具。

       1 服务启动，自动更新文档。

       2 服务启动，能在线测试接口。

       3 不需要维护接口 wiki 或者接口的 gitlab 。

三 swagger 集成

       swagger 已经发布到了新版的 swagger3 ，且相比 swagger2 配置更少，使用更简洁。

3.1 引入依赖

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

3.2 swagger 配置

生成 swagger 配置类

package com.sb.config;
 
import io.swagger.annotations.ApiOperation;
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;
 
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot整合swagger构建api文档")
                .description("更多问题请关注'新猿一马'公众号")
                .contact(new Contact("新猿一马","https://blog.csdn.net/jack1liu","15810361169@163.com"))
                .version("1.0")
                .build();
    }
}

启动类添加 @EnableOpenApi 启动 Swagger。

package com.sb;
 
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@MapperScan(basePackages = "com.sb.dao")
@SpringBootApplication
@EnableSwagger2
public class SpringbootSwaggerApplication {
 
    public static void main(String[] args) {
        SpringApplication.run(SpringbootSwaggerApplication.class, args);
    }
 
}

3.3 Restful 接口

package com.sb.controller;
 
import com.sb.domain.User;
import com.sb.dto.RetDTO;
import com.sb.service.UserService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
 
import javax.annotation.Resource;
import java.util.List;
 
@RestController
@RequestMapping(value="/users")
public class UserController {
 
    @Resource
    private UserService userService;
 
    @ApiOperation(value="获取用户列表", notes="")
    @RequestMapping(value={"/list"}, method=RequestMethod.GET)
    public RetDTO<List<User>> getUserList() {
        List<User> r = userService.getUserList();
        return RetDTO.getReturnJson(r);
    }
 
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value="/insert", method=RequestMethod.POST)
    public RetDTO insert(@RequestBody User user) {
        return RetDTO.getReturnJson(userService.add(user));
    }
 
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value="/{id}", method=RequestMethod.GET)
    public RetDTO<User> getUser(@PathVariable Long id) {
        return RetDTO.getReturnJson(userService.getUserById(id));
    }
 
    @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @RequestMapping(value="/{id}", method=RequestMethod.PUT)
    public RetDTO putUser(@PathVariable Long id, @RequestBody User user) {
        return RetDTO.getReturnJson(userService.update(id, user));
    }
 
    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
    public RetDTO deleteUser(@PathVariable Long id) {
        return RetDTO.getReturnJson(userService.delete(id));
    }
 
}

3.4 Swagger3 文档

启动 SpringBoot 项目，访问 http://localhost:8080/swagger-ui/index.html。

四 swagger 注解说明

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

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

微信公众号：「新猿一马」，微信扫一扫。