SpringBoot集成Swagger的详细步骤
目录
一、简介以及使用
二、整合步骤
三、注解说明
一、简介以及使用
号称：世界最流行的API框架
官网：http://swagger.io/
解决什么问题：
在前后台分离的开发模式中，减小接口定义沟通成本，方便开发过程中测试，自动生成接口文档
使用方式：
1、通过官网配置文档，一个接口一个接口编写
2、通多注解配置，动态生成json数据，由框架自动生成代码展示
二、整合步骤
项目框架要求：本文以springboot
1、在pom文件中引入swagger支持的相关依赖---即jar包
org.springframework.boot
spring-boot-starter-web
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
org.springframework.boot
spring-boot-devtools
org.springframework.boot
spring-boot-starter-test
test
2、添加配置---即编写swagger启动类SwaggerConfig.java
package dcc.core;
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;
@Configuration //声明该类为配置类
@EnableSwagger2 //声明启动Swagger2
public class SwaggerConfig{
@Bean
public Docket customDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.epoch.ccfindcars.controller"))//扫描的包路径
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("反向寻车")//文档说明
.version("1.0.0")//文档版本说明
.build();
}
}
3、编写接口文档----即开启spring整合swagger配置
Swagger2 基本使用：
@Api 描述类/接口的主要用途
@ApiOperation 描述方法用途
@ApiImplicitParam 描述方法的参数
@ApiImplicitParams 描述方法的参数(Multi-Params)
@ApiIgnore 忽略某类/方法/参数的文档
Swagger2 使用注解来编写文档：
Swagger2编写接口文档相当简单，只需要在控制层（Controller）添加注解来描述接口信息即可。
package com.epoch.ccfindcars.controller;
import com.epoch.ccfindcars.entity.LotAddress;
import com.epoch.ccfindcars.entity.LotAddressList;
import com.epoch.ccfindcars.service.LotAddressService;
import com.epoch.ccfindcars.service.LotAddressServiceList;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
/**
* @Author: ljj
* @Description: 反向寻车功能
* @Date:
*/
@RestController
@Api("反向寻车管理功能")
public class ReverseForCarController {
@Autowired
private LotAddressService lotAddressService;
@Autowired
private LotAddressServiceList lotAddressServiceList;
@ApiOperation("通过id确定唯一车牌")
@GetMapping("/getone")
@ApiImplicitParam(name = "id",value = "车位表对应的id",dataType = "int ")
public LotAddress getOneCatLotAddress(int id) {
LotAddress lotAddress = lotAddressService.OneCatLotAddress(id);
return lotAddress;
}
/**
* 快速寻车：通过输入车牌中的一个或多个字母或数字，快速查询车位
*
* @param carLicense
* @return lotAddressList
*/
@ApiOperation("通过车牌号，获取相关车牌列表")
@GetMapping("/serchlike")
@ApiImplicitParam(name = "carLicense",value = "车牌号",dataType = "String")
public List getCarLotAddress(String[] carLicense) {
StringBuffer sc = new StringBuffer();
for (int i = 0; i < carLicense.length; i++) {
sc.append(carLicense[i]);
}
String s = sc.toString();
System.out.println(s);
List lotAddressList = lotAddressServiceList.getCatAllRow(s);
return lotAddressList;
}
@ApiOperation("通过车位号来获取车位")
@GetMapping("/findcar")
@ApiImplicitParam(name = "carAddress",value = "车位号",dataType = "String")
public List getCarAddressByCarAddress(String carAddress) {
List carAddressByCarLicense = lotAddressService.findCarAddressByCarLicense(carAddress);
return carAddressByCarLicense;
}
}
4查阅接口文档
编写文档完成之后，启动当前项目，在浏览器打开：
[ http://localhost:8080/swagger-ui.html ] --（端口根据自己设置来写）看到效果如下：
5测试接口
Swagger2的强大之处不仅在于快速生成整洁优雅的RestAPI文档，同时支持接口方法的测试操作（类似于客户端PostMan）。
以通过车位号获取车位为例，随便输入参数5，直接点击“试一下”按钮：
6.此外，本教程还额外提供了UI汉化教程，去除阅读官方英文界面的烦恼。（目前Swagger汉化教程是找不到的，因为官方手册实在写得太烂。。）
①.默认的英文界面UI
想必很多小伙伴都曾经使用过Swagger，但是打开UI界面之后，却是下面这样的画风，纯英文的界面并不太友好，作为国人还是习惯中文界面。
②.定制中文界面
2.1添加首页和译文
重点来了，在src/main/resources目录下创建META-INF\resources目录，然后创建一个名称为"swagger-ui.html" 的HTML文件。如图：
注意文件名不要起错，接下来将下面这段内容原封不动的拷贝进去。
Swagger UI
OK 大功告成 我们访问 http://localhost:4040/swagger-ui.html 看看显示效果：
2.2更详细的译文翻译（非必需）
如果想进一步调整译文，可以在META-INF\resources\webjars\springfox-swagger-ui\lang 目录下添加zh-cn.js文件.
然后在译文（zh-cn.js ）根据个人喜好来添加翻译内容，如下
'use strict';
/* jshint quotmark: double */
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":"服务器返回"
});
三、常用注解说明
1、常用注解
@Api()用于类；
表示标识这个类是swagger的资源
@ApiOperation()用于方法；
表示一个http请求的操作
@ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
@ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
@ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
@ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
@ApiResponse
返回参数
2、具体使用
@Api()用于类；
参数：
tags:表示说明，tags如果有多个值，会生成多个list
value:已废用
hidde:无效果
description:接口说明
代码：
界面效果：
@ApiOperation()用于方法；
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）
代码:
文档效果：
@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
name–参数名
value–参数说明
dataType–数据类型
paramType–参数类型
@ApiResponse
返回参数说明
response：返回的对象信息
code：返回的状态信息
message：返回的文本信息
对象信息具体注释
@ApiModelProperty
对象字段说明
value：字段名称
example: 字段说明