900字范文 > springboot（05）整合 Swagger3 生成 API 接口文档

springboot（05）整合 Swagger3 生成 API 接口文档

时间：2018-07-14 00:05:25

Spring Boot 集成 Swagger3

Swagger是一种开源的API文档工具，它可以自动生成RESTful API文档，让开发者可以更容易地理解和使用API。使用Swagger可以提高开发效率，减少文档编写的工作量，并降低开发者之间的沟通成本。Swagger可以生成各种不同类型的文档，包括HTML、PDF、JSON和XML等。将Swagger与Spring Boot结合使用可以更加方便地生成API文档，并提供实时的API测试功能。使用Swagger可以提高API的可读性和可维护性，使API更易于开发人员和用户使用。

引入依赖

Swagger3 中，我们不需要再引入两个不同的依赖了，我们只需要引入一个依赖就足够，具体引入的依赖如下：

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

构建 Swagger 配置类

推荐大家在项目配置文件application.yml中添加关于 Swagger 开关的配置，比如这里我添加的配置如下，true则代表开启 Swagger，false则表示关闭 Swagger。

spring:mvc:pathmatch:matching-strategy: ANT_PATH_MATCHERswagger:enabled: true

配置完成之后，我们就需要在 Swagger 配置类中获取 Swagger 开关的值了，关于具体用法就可以看下边配置代码。

package com.cunyu.springbootswagger3demo.config;import org.springframework.beans.factory.annotation.Value;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.oas.annotations.EnableOpenApi;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import java.util.ArrayList;@Configuration@EnableOpenApipublic class SwaggerConfig {/*** 用于读取配置文件 application.properties 中 swagger 属性是否开启*/@Value("${swagger.enabled}")Boolean swaggerEnabled;@Beanpublic Docket docket() {return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())// 是否开启swagger.enable(swaggerEnabled).select()// 过滤条件，扫描指定路径下的文件.apis(RequestHandlerSelectors.basePackage("com.buba.controller"))// 指定路径处理，PathSelectors.any()代表不过滤任何路径//.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {/*作者信息*/Contact contact = new Contact("XX", "", "XXX@");return new ApiInfo("Spring Boot 集成 Swagger3 测试","Spring Boot 集成 Swagger3 测试接口文档","v1.0","https://cunyu1943.github.io",contact,"Apache 2.0","/licenses/LICENSE-2.0",new ArrayList());}}

编写实体类

完成上面的步骤之后，我们的 Swagger 就配置好了，接下来我们就添加一个接口来看看

这里我以一个用户类为实例，带有name、age两个属性，也就是本文一开始项目结构截图中entity包下的内容。

package com.cunyu.springbootswagger3demo.entity;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import lombok.AllArgsConstructor;import lombok.Data;import lombok.NoArgsConstructor;@Data@AllArgsConstructor@NoArgsConstructor@ApiModel("用户实体类")public class User {@ApiModelProperty(value = "姓名", required = true, example = "村雨遥")private String name;@ApiModelProperty(value = "年龄", required = true, example = "20")private Integer age;}

这里写了两个接口，一个是直接传参，另一种是通过利用创建的User实体类来传输，也就是项目结构中controller包中的内容。

package com.cunyu.springbootswagger3demo.controller;import com.cunyu.springbootswagger3demo.entity.User;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RequestBody;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RestController;@Api(tags = "测试")@RestController@RequestMapping("/user")public class UserController {@ApiOperation("测试接口1")@PostMapping("/show1")public String show1(@ApiParam(value = "姓名", required = true, example = "村雨遥") @RequestBody String name) {return "hello," + name + ",welcome to springboot swagger3！";}@ApiOperation("测试接口2")@PostMapping("/show2")public String show2(@ApiParam(value = "用户对象", required = true) @RequestBody User user) {return "hello," + user.getName() + ",welcome to springboot swagger3！";}}