Swagger 不生成 JSON

Question

Swagger 不会生成 JSON 文件。我的 POM 看起来是这样的：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>my.project</groupId>
        <artifactId>my-restservice</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>my-restservice</artifactId>
    <packaging>war</packaging>

    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <artifactId>maven-war-plugin</artifactId>
                    <version>3.1.0</version>
                    <configuration>
                        <failOnMissingWebXml>false</failOnMissingWebXml>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>com.github.kongchen</groupId>
                    <artifactId>swagger-maven-plugin</artifactId>
                    <version>3.1.4</version>
                    <configuration>
                        <apiSources>
                            <apiSource>
                                <locations>my.path.to.the.service</locations>
                                <info>
                                    <title>${project.name}</title>
                                    <version>${project.version}</version>
                                </info>
                                <swaggerDirectory>${project.build.directory}/src</swaggerDirectory>
                                <outputFormats>json</outputFormats>
                            </apiSource>
                        </apiSources>
                    </configuration>
                    <executions>
                        <execution>
                            <phase>compile</phase>
                            <goals>
                                <goal>generate</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>

    <dependencies>
        <dependency>
            <groupId>javax</groupId>
            <artifactId>javaee-api</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <version>1.5.16</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-jaxrs</artifactId>
            <version>1.5.16</version>
        </dependency>
    </dependencies>
</project>

这是我实现的一个 REST 接口：

@Path("/data")
@SessionScoped
@Api(value = "data")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class Data implements Serializable {
    private static final long serialVersionUID = 1L;

    @EJB
    private DataApi d;

    @GET
    @ApiOperation(value = "Returns all data")
    public Collection<DataObject> getData() {
        // Removed.
    }

    @GET
    @Path("{id}")
    @ApiOperation(value = "Returns data by id")
    public DataObject getData(@PathParam("id") Long id) {
        // Removed.
    }
}

我删除了潜在的敏感信息。现在，当我通过mvn clean install 构建项目时，不会生成 JSON 文件。我没有使用任何 JAX-RS 实现，而只是使用普通的 servlet。我不确定这是否有效。我错过了什么？

Answer 1

刚刚发现至少两个问题。解决问题后，使用mvn clean compile命令生成JSON文件。

1。 pom.xml:build:pluginManagement vs plugins

swagger-maven-plugin有pluginManagement的定义，但实际上并没有用到。有必要在plugins 中包含另外插件参考：

<project ...>
    <build>
        <pluginManagement>
            ...
        </pluginManagement>

        <plugins>
            <plugin>
                <groupId>com.github.kongchen</groupId>
                <artifactId>swagger-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

2。 locations规范

当前实现中缺少location 元素，但它必须在这里：

可以在这里配置包含 Swagger 的注解 @Api 的类，或者包含这些类的包。多个值必须用逗号分隔。示例：<locations><location>com.github.kongchen.swagger.sample.wordnik.resource</location><location>com.github.kongchen.swagger.sample.wordnik.resource2</location></locations>

——GitHub - kongchen/swagger-maven-plugin: JAX-RS & SpringMVC supported maven build plugin, helps you generate Swagger JSON and API document in build phase.

总而言之，locations 规范必须更正，例如如下：

<locations>
    <location>com.thecompany.service.Data</location>
</locations>

希望这会有所帮助。