对于咱后台来说,写完代码再写文档是十分难受的(主要是自己写的代码都不想看第二眼)
上干货
一.在pom.xml中引入 swagger 依赖
<!-- Swagger2 API-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.1</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.1</version>
</dependency>
<!-- 防止使用 swagger 测接口时入参错误 -->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
二.编写 Swagger2Config 文件
@Configuration
@EnableSwagger2
public class Swagger2 implements WebMvcConfigurer {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("xxxx文档")
.description("xx文档")
.termsOfServiceUrl("http://dev-master.zgzhongnan.com")
.contact("xxxx")
.version("1.0")
.build();
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源无法访问
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
/**
* 配置servlet处理
*/
@Override
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
}
三.编写 controller 类
@Api(tags = "设备管理", description = "萤石设备管理")
@RestController
@RequestMapping("/smart/equipo")
public class EquipoController {
@Resource
EquipoAPIService equipoAPIService;
@ApiOperation(value = "添加设备", notes = "添加设备")
@ApiImplicitParams(
{
@ApiImplicitParam(name = "houseId" ,value = "房屋id",required = true,paramType="query",dataType = "Long"),
@ApiImplicitParam(name = "userId" ,value = "用户id",required = true,paramType="query",dataType = "Long"),
@ApiImplicitParam(name = "deviceSerial" ,value = "设备序列号",required = true,paramType="query",dataType = "String"),
@ApiImplicitParam(name = "validateCode" ,value = "设备验证码",required = true,paramType="query",dataType = "String")
}
)
@ApiResponses({
@ApiResponse(code=200,message="操作成功")
})
@PostMapping("/addEquipo")
@ResponseBody
public JSONObject addEquipo(Long houseId,Long userId,String deviceSerial,String validateCode) {
return equipoAPIService.addEquipo(houseId,userId,deviceSerial,validateCode);
}
}
四.访问 Swagger 页面
浏览器输入 ip:端口/项目地址/swagger-ui.html
五.注意事项(精华)
- 大家在引入 swagger 的时间千万不要引入太新的版本,因为你可能会踩未知的雷
- 建议在引入 swagger 时同时引入 swagger-annotations swagger-models ,不然你可能遇到传参失败的问题
- 虽然我们配置了重写SpringBoot默认静态资源访问地址,但我们也要注意自己所用的框架中有木有重写SpringBoot静态资源这块的代码,要不然你会一直访问不到 swagger-ui.html 页面
- 在 controller 类中 尽量使用 @ApiImplicitParam 注解定义方法入参,不要用 @ApiParam 注解,@ApiImplicitParam 注解中的paramType 类型没特殊要求就写 query ,不要问为什么,自己试试就知道了