- A+
所属分类：swagger
前后端分离
最常见的：Vue + SpringBoot
前后端分离，后台负责写接口。随着接口越来越多，随时改变接口的可能性也很大，大家争吵是很正常的。
解决方案
-
先指定计划提纲，事实更新API，降低集成风险
-
传统是需要自己去维护一个doc的文档或者公司统一放在一个接口清单的web服务上。每次开发者需要单独添加上去。修改后还需要维护。
-
前后端分离：
-
前端测试后端接口：postman，就为了测一个接口还要下载第三方软件，太奢侈了
-
后端提供接口，实时更新消息及变动
现接入swagger，通过简单的注解即可生成文档，并且随着接口变化自动会变化。统一管理方便快捷
Swagger
-
号称最流行的API框架
-
RestFul Api 文档在线自动生产，Api文档与定义同步更新
-
直接运行，可以在线测试接口
-
支持多种语言（java、php等）
SpringBoot集成Swagger
1.新建SpringBoot项目
2.导入依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
3.随便写一个controller接口，比如 hello
4.配置swagger2，swagger2 是新版的，和swagger 是不一样的哦！
/**
* @author : aBiu---
*
* create at: 2019-12-20 16:20
*
* description: api接口配置
*/@Configuration@EnableSwagger2 // 开启public class SwaggerConfig {
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("API接口文档") //页面标题
.description("接口管理")//详细描述
.version("1.0.0") //版本号
.build();
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // 需要上面定义的ApiInfo，信息显示到页面上
.groupName("aBiu") // 分组，如果想搞多个分组，就写多个Docket 的示例就行了
.select()
.apis(RequestHandlerSelectors.basePackage("com.*")) //这里写的是API接口所在的包位置，也可以设置其他扫描方式
.paths(PathSelectors.any()) // 过滤，有好几种方式可以设置
.build();
}}
5.测试运行，然后访问：http://localhost:8080/swagger-ui.html 或 http://localhost:8080/swagger-ui/index.html
由于版本的不同，可能名字不一样，具体可以到jar包里去看一下就好了
Swagger注解
@Api： 修饰类，一般来描述Controller的@ApiOperation： 描述类的 方法 或者 接口@ApiParam： 单个参数描述@ApiModel： 用在实体类上面@ApiProperty： 实体类里面的属性@ApiImplicitParam： 用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息 name：参数名 value：参数的汉字说明、解释 required：参数是否必须传 paramType：参数放在哪个地方 · header --> 请求参数的获取：@RequestHeader · query --> 请求参数的获取：@RequestParam · path（用于restful接口）--> 请求参数的获取：@PathVariable · body（不常用） · form（不常用） dataType：参数类型，默认String，其它值dataType="Integer" defaultValue：参数的默认值 其它若干@ApiResponse： 描述HTTP响应其中1个的描述@ApiResponses： 描述出HTTP响应整体描述@ApiClass@ApiError@ApiErrors@ApiParamImplicit@ApiParamsImplicit
示例：一个接口的说明（controller类）
/**
* XXX 认证人员信息接口
* @param signerType
* @param certType
* @param certNo
* @param name
* @param phoneNo
* @param cardNo
* @param signSupplier
* @param authType
* @param notifyUrl
* @return
*/
@ApiOperation(value = "XXX 的接口", httpMethod = "POST")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "String", name = "signerType", dataType = "String", required = true, value = "签署人类型:1.个人，2.企业"),
@ApiImplicitParam(paramType = "String", name = "certType", dataType = "String", required = false, value = "证件类型:签署人类型是个人时必填"),
@ApiImplicitParam(paramType = "String", name = "certNo", dataType = "String", required = false, value = "签署人类型:签署人类型是个人时必填"),
@ApiImplicitParam(paramType = "String", name = "name", dataType = "String", required = true, value = "姓名"),
@ApiImplicitParam(paramType = "String", name = "phoneNo", dataType = "String", required = false, value = "手机号:签署人类型是个人时必填"),
@ApiImplicitParam(paramType = "String", name = "notifyUrl", dataType = "String", required = false, value = "回调地址")
})
@PostMapping("/signerInfo")
public ResultInfo signerInfo(String signerType, String certType, String certNo, String name, String phoneNo, @RequestParam(required = false) String notifyUrl){
return contractService.signerInfo(signerType,certType,certNo,name,phoneNo,cardNo,signSupplier,authType,notifyUrl);
}
项目发布上线时候，一定要记得，一定要记得，把swagger 关闭，因为你不可能让用户看到你的接口吧？
生成漂亮的ui界面
加入依赖
<dependency> <groupId>com.github.caspar-chen</groupId> <artifactId>swagger-ui-layer</artifactId> <version>1.1.3</version> </dependency>
访问地址 http://localhost:8080/docs.html
这个好像没有分组的属性，如果swagger配置时候加了分组，在这里会有异常
