Springboot 技术整合--笔记8--现有项目集成swagger2

关键步骤

• 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导入包

        

        
            io.springfox
            springfox-swagger2
            2.8.0
        
        
            io.springfox
            springfox-swagger-ui
            2.8.0
        

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 注解使用技巧