swagger如何使用（5分钟搞定swagger集成和应用）

Restful Api 是当前流行的API规范，API文档编写是一件很重要的事情，也是一件很头疼的事情，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，有效缓解编写文档的痛苦和提高文档的及时性，我来为大家科普一下关于swagger如何使用?下面希望有你要的答案，我们一起来看看吧!

swagger如何使用

Restful Api 是当前流行的API规范，API文档编写是一件很重要的事情，也是一件很头疼的事情，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，有效缓解编写文档的痛苦和提高文档的及时性。

本文将使用 Swagger 2 规范的 Springfox 实现来了解如何在 Spring Boot 项目中使用 Swagger，主要包含了如何集成和使用Swagger 自动生成文档。

集成swagger

添加依赖

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>

增加配置类

Springfox 提供了一个 Docket 对象，让我们可以灵活的配置 Swagger 的各项属性。下面我们新建一个SwaggerConfig.java 类，并增加如下内容:

@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket getDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } }

注意: @Configuration 是告诉 Spring Boot 需要加载这个配置类，@EnableSwagger2 是启用 Swagger2，如果没加的话自然而然也就看不到后面的验证效果了。

验证

地址：http://localhost:8081/test/v2/api-docs

浏览器中输入上述地址会返回json格式数据，swagger集成完成，如果需要可视化展示则需要集成swagger ui，集成方式如下。

集成swagger ui

添加依赖

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>

验证

验证地址：http://localhost:8081/test/swagger-ui.html

浏览器输入上述地址，即可正常访问。至此swagger ui集成完成。

swagger ui页面

使用

1、给接口增加标签信息

通过在控制器类上增加@Api 注解，可以给接口增加标签信息。

package com.example.demo.controller; import com.example.demo.model.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; import java.util.ArrayList; import java.util.List; @Api(tags = "用户信息接口") @RestController @RequestMapping("/user") public class UserInfoController { @ApiOperation("query users info") @RequestMapping(value="/info",method= RequestMethod.GET) public List<User> queryUsersInfo(){ User user1 = new User(); user1.setAge(18); user1.setName("Tom"); User user2 = new User(); user2.setAge(19); user2.setName("Tomas"); List<User> list = new ArrayList<>(); list.add(user1); list.add(user2); return list; } }

2、添加接口的描述

通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述，代码示例同上。增加接口标签和描述信息后，展示如下所示。

接口展示和请求实例

3、添加实体描述

可以通过 @ApiModel 和 @ApiModelProperty 注解来对我们 API 中所涉及到的对象做描述。

package com.example.demo.model; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel("用户实体") public class User { @ApiModelProperty("姓名") private String name; @ApiModelProperty("年龄") private int age; public String getName() { return name; } public void setName(String name) { this.name = name; } public int getAge() { return age; } public void setAge(int age) { this.age = age; } }

对应model视图如下：

model展示

4、接口过滤

Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解，另一种是在 Docket 上增加筛选。Docket 类提供了 apis() 和 paths()两 个方法来帮助我们在不同级别上过滤接口：

apis()：这种方式我们可以通过指定包名的方式，让 Swagger 只去某些包下面扫描。

paths()：这种方式可以通过筛选 API 的 url 来进行过滤。

生产环境关闭swagger

1、在application.properties文件中增加

#是否激活 swagger true or false swagger.is.enable=false

2、在swagger配置类Docket中增加enable(swagger_is_enable)

@Configuration @EnableSwagger2 public class SwaggerConfig { @Value("${swagger.is.enable}") private boolean swagger_is_enable; @Bean public Docket getDocket() { return new Docket(DocumentationType.SWAGGER_2) .enable(swagger_is_enable) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } }

可以通过各环境的application.properties中的swagger.is.enable配置项控制swagger功能的开启和关闭。