Spring Boot整合Swagger 2

Spring Boot整合Swagger 2

1. Swagger 2简介

在前后端分离开发中,为了减少与其他团队的沟通成本,-般构建一份RESTful API文档来描述所有的接口信息,但是这种做法有很大的弊端,分别说明如下:

  • 接口众多,编写RESTful API文档工作量巨大,因为RESTful API文档不仅要包含接口的基本信息,如接口地址、接口请求参数以及接口返回值等,还要包含HTTP请求类型、HTTP请求头、请求参数类型、返回值类型、所需权限等。
  • 维护不方便, 一旦接口发生变化,就要修改文档。
  • 接口测试不方便, 一般只能借助第三方工具(如Postman)来测试。

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

Swagger2可以非常轻松地整合到Spring Boot项目中,下 面来看如何整合。

2. 整合Spring Boot

首先创建Spring Boot Web项目,添加Swagger 2相关依赖,代码如下:


    io.springfox
    springfox-boot-starter
    3.0.0


    io.swagger
    swagger-annotations
    1.5.22


    io.swagger
    swagger-models
    1.5.22

注意:因为我这里引入的 swagger ui2.7 以上的版本,所以还需要引入 guava,否则会因为 guava 兼容性问题造成项目启动报错(无法启动)。SpringBoot 版本 2.2.6.RELEASE,版本不能高与这个版本,否则 Swagger 版本不匹配报错。

接下来创建Swagger 2的配置类,代码如下:

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("suohechuan.testforever"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2接口规范")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://localhost:8080/")
                //版本号
                .version("1.0.0")
                .build();
    }
}

代码解释:

  • 通过apis方法配置要扫描的controller位置,通过paths方法配置路径。

  • 在apiInfo中构建文档的基本信息,例如描述、联系人信息、版本、标题等。

使用@EnableOpenApi注解,启用swagger配置

@EnableOpenApi
@SpringBootApplication
public class TestforeverApplication {
    public static void main(String[] args) {
        SpringApplication.run(TestforeverApplication.class, args);
    }
}

Swagger 2配置完成后,接下来就可以开发接口了,代码如下:

@RestController
@Api(tags = "用户数据接口")
public class UserController {
    @ApiOperation(value = "查询用户", notes = "根据 id 查询用户")
    @ApiImplicitParam(paramType = "path", name = "id", value = "用户 id", required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id) {
        return "查找的用户id是:" + id;
    }

    @ApiOperation(value = "新增用户", notes = "根据传入的用户名和密码添加一个新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "username",
                    value = "用户名", required = true, defaultValue = "test"),
            @ApiImplicitParam(paramType = "query", name = "password",
                    value = "密码", required = true, defaultValue = "123")
    })
    @PostMapping("/user")
    public String addUser(@RequestParam String username, @RequestParam String password) {
        return "新增用户:" + username + " " + password;
    }

    @ApiOperation(value = "删除用户", notes = "根据 id 删除用户")
    @ApiResponses({
            @ApiResponse(code = 200, message = "删除成功!"),
            @ApiResponse(code = 500, message = "删除失败!")
    })
    @DeleteMapping("/user/{id}")
    public Integer deleteUserById(@PathVariable Integer id) {
        return id;
    }

    @ApiOperation(value = "修改用户", notes = "传入用户信息进行更新修改")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user) {
        return user.toString();
    }

    @ApiIgnore
    @GetMapping("/user/test")
    public String test() {
        return "这是一个测试接口,不需要在api文档中显示。";
    }
}

代码解释:

  • @Api注解用在类上,用来描述整个Controller信息。
  • @ApiOperation 注解用在开发方法上,用来描述一个方法的基本信息,value 是对方法作用的一个简短描述,notes则用来备注该方法的详细作用。
  • @ApiImplicitParam注解用在方法上,用来描述方法的参数, paramType是指方法参数的类型,可选值有path (参数获取方式@PathVariable )、query (参数获取方式@RequestParam ). header(参数获取方式@RequestHeader)、body 以及form; name 表示参数名称,和参数变量对应;value是参数的描述信息; required 表示该字段是否必填; defaultValue 表示该字段的默认值。注意,这里的required和defaultValue等字段只是文档上的约束描述,并不能真正约束接口,约束接口还需要在@RequestParam中添加相关属性。
    如果方法有多个参数,可以将多个参数的@ApilmplicitParam注解放到@ApiImplicitParams中。
  • @ApiResponse 注解是对响应结果的描述,code 表示响应码,message 表示相应的描述信息,若有多个@ApiResponse,则放在一个@ApiResponses中。
  • 在 updateUser方法中,使用@RequestBody注解来接收数据,此时可以通过@ApiModel注解和@ApiModelProperty注解配置User对象的描述信息。
  • @ApiIgnore 注解表示不对某个接口生成文档。

(1)@Api 注解标注在类上用来描述整个 Controller 信息。
(2)@ApiOperation 注解标注在方法上,用来描述一个方法的基本信息。
(3)@ApiImplicitParam 注解标注在方法上,用来描述方法的参数。其中 paramType 是指方法参数的类型,有如下可选值:

  • path:参数获取方式为 @PathVariable

  • query:参数获取方式为 @RequestParam

  • header:参数获取方式为 @RequestHeader

  • body

  • form

(4)如果有多个参数,可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中。
(5)@ApiResponse 是对响应结果的描述。code 表示响应码,message 为相应的描述信息。如果有多个 @ApiResponse,则放在一个 @ApiResponses 中。
(6)@ApiIgnore 注解表示不对某个接口生成文档。

接下来启动Spring Boot 项目,在浏览器中输入启动 Spring Boot 项目,在浏览器中输入 http://localhost:8080/swagger-ui/index.html 即可看到接口文档。即可看到接口文档,如图所示。

Spring Boot整合Swagger 2_第1张图片

你可能感兴趣的:(Spring,Boot,spring,boot)