springboot使用swagger2及遇到的小问题

2022-03-02 05:03:44

微服务的流行提供了诸多的方便，随着也带来了N多的API，而swagger2正是一个对API管理的很好的“工具”，本文主要介绍springboot对swagger2的集成，以及集成中遇到的无法访问的问题。

1、pom添加依赖

      <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>

2、配置swagger的基本信息

创建SwaggerConfig ，内容如下：

package com.mos.eboot.service.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author 小尘哥
 * api 地址：http://localhost:9090/swagger-ui.html
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mos.eboot.service"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("eboot-api文档")
                .description("更多信息，请访问https://www.jianshu.com/u/3979cb11f079")
                .termsOfServiceUrl("https://gitee.com/QuanZhanZhiLu/easy-boot")
                .version("1.0")
                .build();
    }
}

3、swagger的使用

举个栗子：

    @ApiOperation(value = "获取菜单详情",notes = "根据id获取菜单")
    @ApiImplicitParam(name = "id", value = "菜单ID", required = true, dataType = "String", paramType = "query")
    @RequestMapping("get-by-id")
    public ResultModel<SysMenu> getById(@RequestParam("id") String id) {
        SysMenu menu = menuService.selectById(id);
        menu.setParentNode(menuService.selectById(menu.getParentId()));
        return new ResultModel<>(ResultStatus.SUCCESS, menu);
    }

    @ApiOperation(value = "删除菜单",notes = "根据id删除菜单")
    @ApiImplicitParam(name = "id", value = "菜单ID", required = true, dataType = "String", paramType = "query")
    @PostMapping("del-by-id")
    public ResultModel<String> delById(@RequestParam("id") String id) {
        return this.basicResult(menuService.deleteById(id));
    }

4、查看ui界面

访问：http://[ip]:[端口]/swagger-ui.html

404.png

惊不惊喜？意不意外？

5、原因

出了bug当然有解决方案，为什么会出现这问题呢？因为springboot默认的静态资源在static下面，而我们看一下swagger-ui.html的目录结构如下图

swagger

看到这里基本都明白怎么回事儿了，我们只需要重写静态资源的路径即可

6、解决方案

  @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/META-INF/resources/").setCachePeriod(0);
    }

7、API界面

主界面

8、以menu-controller为例

3.png

大家会发现一个问题，“删除菜单”的api只有一个，而“获取菜单”的api则有7个之多，可是代码中我们明明只有一个方法，为什么呢？对，就是@RequestMapping和@PostMapping的区别，这也提醒我们尽可能写代码的时候要规范，一个api只接受一种的请求方式，不能为了方便让后面乱了套了。

码农公寓