简介：Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。本文将通过一个简单的示例，将swagger整合到我们自己的springboot项目中去，生成API文档，并支持API测试。

1.pom文件引入swagger所需依赖

新建一个springboot项目，将所需的Swagger依赖引入，整个pom文件内容入下

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.2.0.RELEASE</version> <relativePath/> </parent> <groupId>com.swagger.demo</groupId> <artifactId>swagger-demo</artifactId> <version>1.0.0</version> <name>swagger-demo</name> <description>Demo project for Spring Boot</description> <properties> <project.bulid.sourceEncoding>UTF-8</project.bulid.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> <java.version>1.8</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- swagger依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>

2.swagger注解

在controller包下新建一个ApiController，随便写几个方法，并加上wagger注解，代码示例入下

package com.swagger.demo.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.*; @Api(value = "ApiController",tags = "api入口") @RestController("/") public class ApiController { @ApiOperation(value = "GET方法",tags = "api入口") @GetMapping("getMethod/{data}") public String getMethod(@ApiParam(value = "携带参数",required = true) @PathVariable("data") String data){ return "这是一个GET方法"+data; } @ApiOperation(value = "POST方法",tags = "api入口") @PostMapping("postMethod") public String postMethod(){ return "这是一个POST方法"; } @ApiOperation(value = "PUT方法",tags = "api入口") @PutMapping("putMethod/{data}") public String putMethod(@ApiParam(value = "携带参数",required = true) @PathVariable("data") String data){ return "这是一个PUT方法"+data; } @ApiOperation(value = "DELETE方法",tags = "api入口") @DeleteMapping("deleteMethod/{data}") public String deleteMethod(@ApiParam(value = "携带参数",required = true) @PathVariable("data") String data){ return "这是一个DELETE方法"+data; } }

controller的内容非常简单，本次只是一个简单的整合示例，所以其他的service啥的就懒得弄了，下面讲解下每个注解的意思。

注解名说明参数内容@Api作用于类，标识这个类是一个swagger资源value:描述，tags:标签，相同的标签会存放到一起，以list形式呈现@ApiOperation标识这是一个http请求操作value:方法描述，tags:属于哪个标签下@ApiParam用于方法参数name:参数名，value:参数描述，required:是否必填

除此之外，还有一些其他的注解，如@ApiModel、@ApiModelProperty、@ApiIgnore，本文没有使用，可自行百度后尝试一下。

3.配置swagger

新建一个config包，创建一个wagger配置类，代码如下。

package com.swagger.demo.config; 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; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * Swagger2 配置类 */ @EnableSwagger2 @Configuration public class Swagger2Config { @Bean public Docket swaggerPluginConfig(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //Api文档描述 .select() //选择哪些路径和Api会生成文档 .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller")) //对指定路径下Api进行监控 .paths(PathSelectors.any()) //对所有路径进行监控 .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("Test Demo接口文档") .description("API 接口文档") .termsOfServiceUrl("http://localhost") .version("1.0.0") .contact(new Contact("takano","","xxxxxx@qq.com")) .build(); } }

注意：一定要添加@EnableSwagger2注解

4.测试

启动项目，输入网址http://localhost:8080/swagger-ui.html，即可进入到swagger的ui界面，如下图所示

可以看到我们暴露的api接口，点击可以在线测试，我在这里测试下GET方法，点击GET方法，界面如下

点击try it out，我们设置了data为必填参数，所以这里随便填写，之后点击Execute，便可看到执行返回的结果，如下图所示。

至此，Springboot整合swagger的小示例就完成了，通过使用swagger可以帮助我们快速的生成api文档，方便调试接口，用起来很舒服。

如有错误，欢迎批评指正，我会及时修改。