swagger2
简介
Swagger 是一款RESTFUL接口的文档在线自动生成 功能测试功能软件。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
发展原因
在一些大型的项目当中，前后端也分离了，接口非常的多并且会伴随着改动，原来是前端和后端开会定接口，然后分别开发的，但是这样的话会产生时间或者说是扯皮的各种非开发的成本，所以swagger就出现了，通常意义上上他就是一个节约前后端沟通成本的一个工具
使用
1.导入依赖
代码语言：javascript复制 <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>2.配置bean
代码语言：javascript复制package kj08.swaggerdemo.conf;
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;
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
//api接口包扫描路径
public static final String SWAGGER_SCAN_BASE_PACKAGE = "kj08.swaggerdemo.controller";
public static final String VERSION = "1.0.0";
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
.paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口调用文档") //设置文档的标题
.description("随便设置") // 设置文档的描述
.version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
.termsOfServiceUrl("http://www.baidu.com") //这里配置的是服务网站
.build();
}
}
3.在controller上面加对应注解
代码语言：javascript复制package kj08.swaggerdemo.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
@Api(description = "学生模块接口")
@RestController
@RequestMapping("/stu")
public class StudentController {
@ApiOperation(value="登录", notes="登录", produces="application/json")
@RequestMapping(value="/login", method= RequestMethod.POST)
public String login(@RequestParam String user, @RequestParam String pwd) {
return "SUCESS";
}
}
4.访问http://localhost:8080/swagger-ui.html
相关注解
@Api ：请求类的说明
代码语言：javascript复制@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="该参数没什么意义，所以不需要配置"举例
代码语言：javascript复制@Api(tags = "账户相关模块")
@RestController
@RequestMapping("/api/account")
public class AccountController {
//TODO
}@ApiOperation：方法的说明
代码语言：javascript复制@ApiOperation："用在请求的方法上，说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"举例：
代码语言：javascript复制@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
@RequestBody @Valid PasswordModel passwordModel) {
//TODO
}@ApiImplicitParams、@ApiImplicitParam：方法参数的说明
代码语言：javascript复制@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="int"
defaultValue：参数的默认值举例：
代码语言：javascript复制@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//TODO
return AjaxResult.OK();
}@ApiOperation("根据部门Id删除")
@ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
//TODO
}@ApiResponses、@ApiResponse：方法返回值的说明
代码语言：javascript复制@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类举例
代码语言：javascript复制@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@ApiResponses({
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径找不到")
})
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
@RequestBody @Valid PasswordModel passwordModel) {
//TODO
}@ApiModel：用于JavaBean上面，表示一个JavaBean
代码语言：javascript复制@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
（这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiI@ApiModelProperty：用在JavaBean的属性上面，说明属性的含义
举例
代码语言：javascript复制@ApiModel("修改密码所需参数封装类")
public class PasswordModel
{
@ApiModelProperty("账户Id")
private String accountId;
//TODO
}@ApiParam
代码语言：javascript复制放在方法参数上面的
name String “” 参数名称，参数名称将从 filed/method/parameter 名称中派生，但你可以覆盖它，路径参数必须始终命名为它们所代表的路径部分
value String “” 参数简单描述
defaultValue String “” 描述参数默认值
allowableValues String “” 可接收参数值限制，有三种方式,取值列表，取值范围
required boolean false 是否为必传参数, false:非必传; true:必传
access String “” 参数过滤，请参阅:io.swagger.core.filter.SwaggerSpecFilter
allowMultiple boolean false 指定参数是否可以通过多次出现来接收多个值
hidden boolean false 隐藏参数列表中的参数
example String “” 非请求体(body)类型的单个参数示例
examples Example @Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例，仅适用于请求体类型的请求
type String “” 添加覆盖检测到类型的功能
format String “” 添加提供自定义format格式的功能
allowEmptyValue boolean false 添加将格式设置为空的功能
readOnly boolean false 添加被指定为只读的能力
collectionFormat String “” 添加使用 array 类型覆盖 collectionFormat 的功能
@ApiIgnore
@ApiIgnore 可以用在类、方法上，方法参数中，用来屏蔽某些接口或参数，使其不在页面上显示。
导入postman
将ui页面的api-docs复制
打开postman-->import-->import Form Link
