一、为什么使用Swagger2
当下很多项目都采用前后端分离的开发模式，前端和后断的工作由不同的团队完成。在这种开发模式下，维持一根及时更新并且完整的Rest API文档会极大的提高我们的工作效率。传统的wen是由后端开发人员手动编写，这种方式很难保证文档的及时性，久而久之这种方式书写的文档也就失去了意义。Swagger优点：
1、代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
2、跨语言性，支持 40 多种语言。
3、Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
4、还可以将文档规范导入相关的工具（例如 Postman、SoapUI）, 这些工具将会为我们自动地创建自动化测试。
二、使用Swagger
1.Maven坐标
<groupId>io.springfox
<artifactId>springfox-swagger2
<version>2.7.0
<groupId>io.springfox
<artifactId>springfox-swagger-ui
<version>2.7.0
</dependency>
2.新建SwaggerConfig
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public DocketproductApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfoapiInfo(){
return new ApiInfoBuilder().title("加解密服务api")
.description("1.0")
.build();
}
}
3.在shiro中为swagger2放行
如果在项目中使用了shiro，需要在shiro中放行swagger2的相关资源
三、Swagger注解详解
1、@Api
@Api:放在请求的类上，与@Controller并列，说明类的作用，如用户模块，订单类等。tags="说明该类的作用"value="该参数没什么意义，所以不需要配置"。
2、@ApiOperation
@ApiOperation："用在请求的方法上，说明方法的作用"value="说明方法的作用"notes="方法的备注说明"
3、@ApiImplicitParams、@ApiImplicitParam
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="int"
defaultValue：参数的默认值
举例：
@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")
publicAjaxResultlogin(@RequestParamStringmobile,@RequestParamStringpassword,@RequestParamIntegerage){//TODOreturnAjaxResult.OK();}
4、@ApiResponses、@ApiResponse
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
举例：
@ApiOperation(value ="对称加密算法加密", notes ="使用设置的默认对称加密算法对数据进行加密，返回值中的data为string类型，加密失败data为null")
@PostMapping("symmetryEncryption")
@ApiResponses(value = {
@ApiResponse(code =1000, message ="成功"), @ApiResponse(code =1001, message ="失败")
})
public ResultsymmetryEncryption(@ApiParam("要加密的数据")@RequestParam(value ="data") String data) {
try {
String algorithm = SystemParameter.getSymmetryAlgorithm();
EncryptionAlgorithm encryptionAlgorithm = SymmetryEncryptUtil.algorithmType(algorithm);
String encryption = SymmetryEncryptUtil.encryption(encryptionAlgorithm, data, path);
return new Result<>(1000, "", encryption);
}catch (Exception e) {
e.printStackTrace();
return new Result<>(1001, "", null);
}
}
5、@ApiParam
对一个参数进行说明
6、@ApiModel、@ApiModelProperty
@ApiModel：用于JavaBean的类上面，表示此JavaBean整体的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty:用在JavaBean的属性上面，说明属性的含义
举例：
@ApiModel("修改密码所需参数封装类")
publicclassPasswordModel{
@ApiModelProperty("账户Id")
privateStringaccountId;
}
四、API文档浏览地址
配置好Swagger2并适当添加注解后，启动SpringBoot应用，访问http://localhost:8080/swagger-ui.html 即可浏览API文档。合理使用上面的注解会极大的提高我们文档的可读性。
五、将Swagger2的API接口导入Postman
打开postman->import->import Form Link，输入文档url
代码示例：https://github.com/ChunyuePeng/swagger2demo.git
