Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测
Swagger 的优势
支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术
提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口
现有项目使用的是spring框架 现需要集成Swagger,步骤如下:
1.添加依赖
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
<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>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
</dependency>
2.创建 Swagger 配置类
package com.swagger.config;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableWebMvc
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//Swagger 开关 配置在配置文件中 测试环境打开 生产环境关闭
@Value(value = "${swagger.enabled:false}")
private Boolean swaggerEnabled;
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
// 是否开启
.enable(swaggerEnabled)
.select()
//只显示添加@Api注解的类
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXX系统")
.description("接口文档")
.version("1.0.0")
.build();
}
}
3.在spring.xml 增加扫描配置
<!-- 扫描swagger包路径 -->
<context:component-scan base-package="com.swagger.config"/>
4.后续就可以在controller和entity中 增加注解生成API文档
@RestController
@RequestMapping(value = { "/commodity/" })
// 类上加@Api注解
@Api(value = "/CommodityController", tags = "商品查询接口")
public class CommodityController{
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
// 方法上加ApiOpreation注解
@ApiOperation(value = "根据id获取产品信息", notes = "根据id获取商品信息", httpMethod = "GET", response = Commodity.class)
public ResponseEntity<Commodity> get(@PathVariable Long id) {
Commodity commodity= new Commodity();
commodity.setName("T恤");
commodity.setId(1L);
return ResponseEntity.ok(commodity);
}
}
package com.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.Date;
@ApiModel(value = "商品列表查询参数")
@Data
public class Commodity {
@ApiModelProperty(value = "商品名称")
private String name;
@ApiModelProperty(value = "商品 id")
private long id;
}
5.在配置文件中配置开关:swagger.enabled=true 测试环境打开 生产环境关闭
就可以启动项目 访问:http://localhost:8080/项目名/swagger-ui.html 查看api