问题 springboot_Spring Boot整合Swagger及遇到的问题

前后端分离已成为主流的开发模式，前端工程师和后端工程师各自的职责分明，能更加专注于自己的领域，能很大程度的提高工作效率。前后端分离开发模式的关键在于有一份及时完整的API文档。这个文档一般由后端工程师编写，但随着项目的演进和平时对这些API的修改，这些API会发生改变，后端工程师有事忘记或懒得更新文档，导致前端工程师会一脸懵逼吗，增加了沟通成本。所以一个好的API文档工具很是必要。

下面我给大家介绍一个很好用的API文档工具，它就是Swagger，用过它的人都赞不绝口。Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，让我们再修改代码时不需要再去单独的更新文档。Swagger UI 呈现出来的可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

接下来，我带大家走下SpringBoot整合Swagge的步骤。

1、创建Spring Boot Web项目

我使用idea的Spring Initializr工具创建了一个空的Spring Boot项目。您可以通过 Spring Initializr 页面生成一个空的 Spring Boot 项目，下载后再导入idea。

加入web依赖。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency> 

编写API接口

​@RestController
@RequestMapping("/student")
public class StudentController {

    @Autowired
    private StudentService studentService;

    @PostMapping("/add")
    public boolean addUser(@RequestBody Student student) {
        return studentService.addUser(student);
    }
    @GetMapping("/find/{id}")
    public Student findById(@PathVariable("id") int id) {
        return studentService.findById(id);
    }
    @PutMapping("/update")
    public boolean update(@RequestBody Student student) {
        return studentService.update(student);
    }
    @DeleteMapping("/delete/{id}")
    public boolean delete(@PathVariable("id") int id) {
        return studentService.delete(id);
    }
}

2、集成Swagger

经过上面的步骤，我们已经拥有了四个接口，分别是:

1. /student/add：新增学生。
2. /student/find/{id}：根据 id 查询学生。
3. /student/update：更新学生。
4. /student/delete/{id}：根据 id 删除学生。

下面我们将通过集成 Swagger，然后为这 4 个 API 自动生成接口文档。

添加依赖

​<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

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

增加Swagger配置

​@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

@Configuration 是告诉 Spring Boot 需要加载这个配置类，@EnableSwagger2 是启用 Swagger2

3、验证

现在我们已经成功的在 Spring Boot 项目中集成了 Swagger，启动项目后，我们可以通过在浏览器中访问 http://localhost:8080/v2/api-docs 来验证，您会发现返回的结果是一段 JSON 串，可读性非常差。

幸运的是 Swagger2 为我们提供了可视化的交互界面 SwaggerUI，在浏览器中访问 http://localhost:8080/swagger-ui.html 就可以看到效果。

至此。我们完成了再Spring Boot项目中集成Swagger。

4、可能遇到的问题

如果项目中集成了Shiro或Spring Security会把Swagger UI资源拦截，报以下的错，所以需要Swagger UI资源排除。

报错如下：

Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g.  if the api is available at http://example.org/api/v2/api-docs then the base url is http://example.org/api/. Please enter the location manually:

Shiro配置Swagger UI资源排除：

​filterMap.put("/v2/api-docs", "anon");
filterMap.put("/swagger-ui.html", "anon");
filterMap.put("/swagger-resources", "anon");
filterMap.put("/swagger-resources/configuration/ui", "anon");
filterMap.put("/swagger-resources/configuration/security", "anon");
filterMap.put("/webjars/**", "anon");

欢迎关注我的微信公众号，期待与您一起成长。