1. Swagger介绍
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
作用:
- 接口的文档在线自动生成。
- 功能测试。
Swagger是一组开源项目,其中主要要项目如下:
- Swagger-tools: 提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
- Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
- Swagger-js: 用于JavaScript的Swagger实现。
- Swagger-node-express: Swagger模块,用于node.js的Express web应用框架。
- Swagger-ui: 一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。
- Swagger-codegen: 一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。
2. Maven导入依赖
版本号请根据实际情况自行更改。
<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>
3. 创建Swagger配置类
package com.test.swagger.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger2配置类
* 在与SpringBoot集成时,通过@Configuration注解,让Spring来加载该类配置.
* 再通过@EnableSwagger2注解来启用Swagger2.
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* 配置Swagger Docket的bean实例
*/
@Bean
public Docket docket() {
/*
* 设置Swagger在生产环境中使用,在发布..环境不使用
*/
//设置要显示 Swagger环境
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles判断是否处在自己设置的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//配置Api文档的分组 ??? 如何配置多个分组, 配置多个Docket实例即可
.groupName("xxxx")
.enable(flag) // enable 指是否启动Swagger,为false 则Swagger不能再浏览器中访问
.select()
//RequestHandlerSelectors , 配置要扫描接口的方式
//basePackage: 指定要扫描的包
//any(): 扫描全部
//none(): 不扫描
//withClassAnnotation: 扫描类上的注解,参数是一个注解的反射对象
//withMethodAnnotation: 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.test.swagger.controller"))
//paths() 过滤什么路径
//.paths(PathSelectors.ant(/xxx))
.build();
}
/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
* 访问地址:http://项目实际地址/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
//额外信息
Contact contact = new Contact("NAME","URL","EMAIL");
return new ApiInfoBuilder(
title:"SpringBoot中使用Swagger2构建RESTful APIs",
description:"xxxxINFOxxxxxx",
version:"1.0",
termsOfServiceUrl:"xxxxURLxxxxxx",
contact,
license:"Apache 2.0",
licenseUrl:"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
4:丰富文档内容
Swagger使用的注解及其说明:
@Api:用在类上来说明该类的作用
@ApiOperation:给方法添加说明
@ApiImplicitParams : 在方法上包含一组参数说明
@ApiImplicitParam:给方法入参增加说明
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:描述一个Model的信息
@ApiModelProperty:描述一个model的属性
5. 简单的UI
来自官网,与实际访问有差距
总结:
1. 以上Swagger注解给一些难理解的属性或者接口,添加注释信息
2. 接口文档实时更新
3.可以在线测试
[ 在正式发布时,要关闭Swagger ! 处于安全 也节省运行内存]