swagger 初识

openapi 3

参考文档 [1]

pom.xml文件新增依赖：

        <!-- 需要Springboot 3.0+ 以及 JDK17+ -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.2.0</version>
        </dependency>

application.yaml增加配置：

springdoc:
  api-docs:
    path=/api-docs:

springboot 2.0+

参考文档：Setting Up Swagger 2 with a Spring REST API Using Springfox

pom.xml增加依赖：

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

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

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

增加配置代码：

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

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

application.yaml增加配置：

springfox:
  documentation:
    enabled: true

FAQ

1. Failed to start bean 'documentationPluginsBootstrapper'

解决办法：在启动类加一个注解：@EnableWebMvc

2. Could not resolve view with name 'forward:/swagger-ui/index.html' in servlet with name 'dispatcherServlet'

参考文档

[1] SpringBoot集成Swagger3.0

[2] Documenting a Spring REST API Using OpenAPI 3.0

[3] Setting Up Swagger 2 with a Spring REST API Using Springfox

[4] swagger 官网