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 来进行过滤。
生产环境关闭swagger1、在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功能的开启和关闭。
