为什么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>[email protected]</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注释以生成文档/描述。

有关其他读者，请参阅swaggerApiReader中的https://github.com/kongchen/swagger-maven-plugin文档。

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

Answer 2

你需要一个更新/更新的maven-plugin。看看https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-maven-plugin

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