为什么 swagger-maven-plugin 找不到我的 API 操作？

Question

我正在尝试在 Spring Boot 项目中使用 Swagger 2.0 和 swagger-maven-plugin 设置 API 文档。在我的控制器中，我使用 io.swagger.v3.oas 注释：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

@RestController
@RequestMapping("/api")
public class CountryController {

    @Operation(summary = "Read country by ISO 3166-1 alpha-2 code", responses = {
        @ApiResponse(responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Country.class)))
    })
    @RequestMapping(value = { "/country/{key}" }, method = { RequestMethod.GET })
    @PreAuthorize("#oauth2.hasScope('read')")
    Country getCountry(
            @Parameter(name = "key", description = "The ISO 3166-1 alpha-2 code of the country") @PathVariable final String key,
            @Parameter(hidden = true) final Principal principal) {
    return countryService.load(key, UserInSession.fromPrincipal(principal, userDetailsService))
        .orElse(null);
    }
}

在我的 pom.xml 中

        <plugin>
            <groupId>com.github.kongchen</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>${swagger-maven-plugin-version}</version>
            <configuration>
                <apiSources>
                    <apiSource>
                        <springmvc>true</springmvc>
                        <locations>
                            <location>ch.want.funnel.controller</location>
                        </locations>
                        <schemes>
                            <scheme>http</scheme>
                            <scheme>https</scheme>
                        </schemes>
                        <host>www.funnel.travel</host>
                        <basePath>/api</basePath>
                        <info>
                            <title>funnel.travel API</title>
                            <version>${project.version}</version>
                            <description>
                                API document for funnel.travel server
                            </description>
                            <termsOfService>http://www.funnel.travel/license.html</termsOfService>
                            <contact>
                                <email>info@funnel.travel</email>
                                <name>Simon Niederberger</name>
                                <url>http://www.funnel.travel</url>
                            </contact>
                            <license>
                                <url>http://www.funnel.travel/license.html</url>
                                <name>Commercial, all rights reserved</name>
                            </license>
                        </info>
                        <securityDefinitions>
                            <securityDefinition>
                                <name>funnel OAuth</name>
                                <type>oauth2</type>
                                <name>Authorization</name>
                                <in>header</in>
                            </securityDefinition>
                        </securityDefinitions>
                        <outputPath>${basedir}/generated/document.html</outputPath>
                        <swaggerDirectory>${basedir}/generated/swagger-ui</swaggerDirectory>
                        <!-- <swaggerApiReader>com.wordnik.swagger.jaxrs.reader.DefaultJaxrsApiReader</swaggerApiReader> -->
                        <attachSwaggerArtifact>true</attachSwaggerArtifact>
                    </apiSource>
                </apiSources>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
   ...
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-core</artifactId>
        <version>2.0.0</version>
    </dependency>

从 maven 日志中，我看到扫描了 ch.want.funnel.controller 包，但只生成了 /login 和 /error 的 API 路径！我是否缺少注释或插件配置？

我宁愿不切换到 springfox，因为我更喜欢在编译时生成 swagger.json。

谢谢，西蒙

Answer 1

据我所知，Maven 插件默认使用JaxRsReader。这个swaggerApiReader 扫描 JAX-RS 注释以生成文档/描述。

请参阅https://github.com/kongchen/swagger-maven-plugin 中的swaggerApiReader 文档以了解替代读者。

这可能是您的设置中无法识别 Swagger 注释的原因。

Answer 2

您需要更新/更新的 maven 插件。看https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-maven-plugin

您对 OpenAPI 3 使用 Annotations，但对 OpenAPI 2 使用 maven-plugin。