关键步骤
- pom.xml导入包
- Swagger配置
- WebMvc配置添加Swager2的ui资源
- App类添加@EnableSwagger2注解
- 为web api添加api说明&api参数说明
用途
- 自动生成web api 文档
- 检查web api 提供的方法，比如@RequestMapping 提供了PATCH\GET\HEAD\POST\PUT\DEL；如果仅仅要提供Post 请求，那么只要修改注解@RequestMapping ->@PostMapping
正常访问路径
http://localhost:8080/swagger-ui.html
开始撸码
pom.xml导入包
<!--springfox-swagger2 SpringBoot项目集成Swagger2，让你的接口管理轻而易举-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
Swagger配置
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.younghare.wechatTask.controller")) //项目controller需要被扫描的路径
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot lepus利用swagger2构建api文档")
.description("配合免费yapi &pastman一起使用，会让你爱不释手！！！，https://blog.csdn.net/caizhigui/")
.termsOfServiceUrl("http://yapi.yiyehudong.com")
.version("1.0")
.build();
}
}
springboot启动app添加
//@EnableSwagger2注释用于为Spring Boot应用程序启用Swagger2。
@EnableSwagger2
添加注解
运行并访问http://localhost:8080/swagger-ui.html
出现问题，页面显示默认报错页面。后台报错：
No mapping found for HTTP request with URI [/swagger-ui.html] in DispatcherServlet with name ‘dispatcherServlet’
这个错误，是因为静态资源路径映射问题导致。
我们在访问http://localhost/swagger-ui.html时，这个swagger-ui.html相关的所有前端静态文件都在springfox-swagger-ui-2.4.0.jar里面。目录如下：
image.png
SpringBoot自动配置本身并不会把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面。我们加上这个映射即可。构建一个WebMvcConfig 类，代码如下：
@Configuration
public class WebMvcConfig implements WebMvcConfigurer { //WebMvcConfigurerAdapter过时了
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
再次启动项目访问地址
http://localhost:8080/swagger-ui.html
正常访问Swagger2
生产环境禁用Swagger
#是否启用Swagger是在application.properties文件里配置的，配置如下：
#生产环境禁用，设置为false即可。
swagger.enable=true
为web api 添加注释
原来--单参数
@RequestMapping("/robot/delete")
public IJSONResult deleteUser(String wechatId)
修改为--单参数
//api操作说明
@ApiOperation(value="删除robot信息", notes="根据wechatId删除robot信息")
//api 参数说明
@ApiImplicitParam(name = "wechatId", value = "微信ID", required = true,paramType = "query", dataType = "String")
@DeleteMapping("/robot/delete")
public IJSONResult delete(String wechatId) {
原来--多参数
@RequestMapping("/robot/queryPaged") //查询分页
public IJSONResult queryPaged(Integer page,Integer pageSize)
修改为---多参数
@ApiOperation(value = "获取所有机器人", notes = "查询分页数据")
@GetMapping("/robot/queryPaged") //查询分页 RequestMapping 提供了PATCH\GET\HEAD\POST\PUT\DEL
public IJSONResult queryPaged(
@ApiParam(name="page",value="页码",required=false) Integer page,
@ApiParam(name="pageSize",value="每页记录数",required=false) Integer pageSize) {
效果如图
image.png
image.png
关于Swagger2的文章收录
SpringBoot整合Swagger2
SpringBoot集成Swagger2遇到异常：请求不到swagger-ui.html
SpringBoot2.0 整合 Swagger2 ,构建接口管理界面
SpringBoot项目集成Swagger2，让你的接口管理轻而易举
Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据
swagger2的常用注解，传递参数的注意使用方法
超详细 Spring @RequestMapping 注解使用技巧
