前言
Swagger主要用于构建接口API,以方法注释的方式自动化生成API,能够应对接口的变化,减少构建API文档的工作量。
一个对外提供的接口,主要包含以下内容:
- 访问url
- 请求方式:post or get
- 请求参数:参数是否必填
- 返回结果:远程调用都要有规定的错误代码
构建API
ControllerNameController.java
@Api("用在类上,说明该类的作用")
@Controller
@RequestMapping("/api/ControllerName")
public class ControllerNameController {
@ApiOperation(value = "方法说明", notes = "注释,一般出现在方法说明的下方")
@ApiResponses({
@ApiResponse(code = 0, message = "系统提示信息:请求成功"),
@ApiResponse(code = 1, message = "系统提示信息:请求失败原因")
})
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query", name = "param1", value = "param1 参数说明", required = true, dataType = "String", defaultValue = "param1 default value"),
@ApiImplicitParam(paramType = "query", name = "param2", value = "param2 参数说明", required = false, dataType = "Integer", defaultValue = "param2 default value")
})
@PostMapping("/methodName")
@ResponseBody
public TableDataInfo methodName(@RequestParam(name = "param1")String param1,
@RequestParam(name = "param2")Date param2)
{
}
}
配置swagger
Maven依赖
<properties>
<swagger.version>2.9.2</swagger.version>
</properties>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<!-- swagger2-UI-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
SwaggerConfig.java
/**
* Swagger2的接口配置
* @Author waichan
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig
{
/**
* 创建API
*/
@Bean
public Docket createRestApi()
{
return new Docket(DocumentationType.SWAGGER_2)
// 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api,用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描指定包中的swagger注解
//.apis(RequestHandlerSelectors.basePackage("com.waichan.web.controller.project.api"))
// 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo()
{
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title("标题:接口文档")
// 描述
.description("描述:对外接口文档")
// 作者信息
.contact(new Contact("waichan", "https://blog.csdn.net/DMW2016", "594235081@qq.com"))
// 版本
.version("版本号:" + "version")
.build();
}
}