SpringBoot——整合Swagger
2018-12-05 本文已影响81人
Hi_JIAQI
什么是Swagger?
官方说法：Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
目前的个人见解：Swagger类似于Postman接口测试工具，但是其又比Postman强大很多，更加便于前后端交互和API测试,它可以自动生成文档和测试接口的ui，较适用于RESTful风格当中使用。
Swagger的一些常用注解：
通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等
@Api:修饰整个类，用于controller类上（注明当前类的信息）
@ApiOperation:描述一个接口，用户controller方法上（注明方法信息）
@ApiParam:单个参数描述
@ApiModel:用来对象接收参数,即返回对象
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiError ：发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
SpringBoot2.1.1 整合Swagger2:
这里作者使用的是Boot目前的最新版本对Swagger（2.7.0）进行一个简单的整合及汉化，当然2.0以上版本也是通用的（基本没什么冲突的哈！！ 若有问题欢迎留言纠正）
1.通过Maven依赖的方式添加Swagger依赖到pom
<!--Swagger2依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!--Swagger2 UI包 即：可通过html页面去访问Swagger测试接口-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2.书写Swagger在SpringBoot中的配置类
package com.itcast.swaggertest.config;
/**
* @authro JIAQI
* @date 2018/12/4 - 20:51
*/
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//指定提供接口所在的基包
.apis(RequestHandlerSelectors.basePackage("com.itcast.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 该套 API 说明，包含作者、简介、版本、host、服务URL
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("标题：某公司——XXXX——接口文档")
//模板描述
.description("描述：XXXXXXX，具体包括XXX,XXX模板")
.contact(new Contact("作者XX", url, host)) //当然也可以用null来表示
.version("1.0") //对应的版本号
.build();
}
}
3.书写测试类并运行程序
package com.itcast.swaggertest.controller;
/**
* @authro JIAQI
* @date 2018/12/4 - 20:56
*/
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
/**
* @ApiOperation：用在请求的方法上，说明方法的用途、作用 value="说明方法的用途、作用"
* notes="方法的备注说明"
* @ApiImplicitParams：用在请求的方法上，表示一组参数说明
* @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 name：参数名
* value：参数的汉字说明、解释
* required：参数是否必须传
* paramType：参数放在哪个地方
* · header --> 请求参数的获取：@RequestHeader
* · query --> 请求参数的获取：@RequestParam
* · path（用于restful接口）--> 请求参数的获取：@PathVariable
* · body（不常用）
* · form（不常用）
* dataType：参数类型，默认String，其它值dataType="Integer"
* defaultValue：参数的默认值
* @ApiResponses：用在请求的方法上，表示一组响应
* @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400
* message：信息，例如"请求参数没填好"
* response：抛出异常的类
* @ApiModel：用于响应类上，表示一个返回响应数据的信息 （这种一般用在post创建的时候，使用@RequestBody这样的场景，
* 请求参数无法使用@ApiImplicitParam注解进行描述的时候）
* @ApiModelProperty：用在属性上，描述响应类的属性
*/
@Api(tags = "Swagger测试")
@Controller
@Slf4j
public class Mycontroller {
@ApiOperation(value = "查询学生信息接口", notes = "查询学生信息")
@GetMapping("/select")
@ResponseBody
public String selectStudentMsg() {
System.out.println("查询了学生信息");
return "查询学生信息成功";
}
}
4.结果如下:
Swagger接口测试的地址为（8081为你所设置的端口号，以下的页面是有经过汉化的，下面也会详细说下汉化过程）：http://localhost:8081/swagger-ui.html
5.Swagger如何汉化：
首先我们在Maven中所加入的SwaggerUI包中不难看到结果如下：
在倒数第二个我们可以看到swagger-ui.html的html页面，其实这个页面也就是Swagger的测试接口显示页面，那么如何去汉化呢？
1.首先我们应该找到我们所添加版本的swagger-ui.html然后在项目的resources文件下创建META-INF.resources文件；
2.其次复制jar包中的swagger-ui.html到resources下所创建的META-INF.resources文件中；
3.再者在META-INF.resources文件下创建webjars.springfox-swagger-ui.lang(我们也可以去查看jar包中的lang文件，从中不难看出里面是在存放JS文件的，这么写的话也就是为了去替换文本做到进行汉化)；
4.最后我们在文件webjars.springfox-swagger-ui.lang中创建我们所定义的js文件（zh-cn.js），并且在html文件中引入我们所创建的js：
/**
* Created by dell on 2018/12/4.
*/
/* 用户自定义Swagger汉化,可根据自己的需求去做进一步修改*/
window.SwaggerTranslator.learn({
"Warning: Deprecated":"警告：已过时",
"Implementation Notes":"实现备注",
"Response Class":"响应类",
"Status":"状态",
"Parameters":"参数",
"Parameter":"参数",
"Value":"值",
"Description":"描述",
"Parameter Type":"参数类型",
"Data Type":"数据类型",
"Response Messages":"响应消息",
"HTTP Status Code":"HTTP状态码",
"Reason":"原因",
"Response Model":"响应模型",
"Request URL":"请求URL",
"Response Body":"响应体",
"Response Code":"响应码",
"Response Headers":"响应头",
"Hide Response":"隐藏响应",
"Headers":"头",
"Try it out!":"试一下！",
"Show/Hide":"显示/隐藏",
"List Operations":"显示操作",
"Expand Operations":"展开操作",
"Raw":"原始",
"can't parse JSON. Raw result":"无法解析JSON. 原始结果",
"Example Value":"示例",
"Click to set as parameter value":"点击设置参数",
"Model Schema":"模型架构",
"Model":"模型",
"apply":"应用",
"Username":"用户名",
"Password":"密码",
"Terms of service":"服务条款",
"Created by":"创建者",
"See more at":"查看更多：",
"Contact the developer":"联系开发者",
"api version":"api版本",
"Response Content Type":"响应Content Type",
"Parameter content type:":"参数类型:",
"fetching resource":"正在获取资源",
"fetching resource list":"正在获取资源列表",
"Explore":"浏览",
"Show Swagger Petstore Example Apis":"显示 Swagger Petstore 示例 Apis",
"Can't read from server. It may not have the appropriate access-control-origin settings.":"无法从服务器读取。可能没有正确设置access-control-origin。",
"Please specify the protocol for":"请指定协议：",
"Can't read swagger JSON from":"无法读取swagger JSON于",
"Finished Loading Resource Information. Rendering Swagger UI":"已加载资源信息。正在渲染Swagger UI",
"Unable to read api":"无法读取api",
"from path":"从路径",
"server returned":"服务器返回"
});
translator.js为国际化的意思，此js如果不引用的话是会造成汉化失败的！！！
<!--国际化操作：选择中文版 -->
<script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>
