swagger - 生成 REST API 文档的步骤

Question

关闭。这个问题需要更多focused .它目前不接受答案。












想改善这个问题吗？更新问题，使其仅关注一个问题 editing this post .

5年前关闭。




Improve this question




我正在尝试为我现有的一些 REST API 生成基于 Swagger 的 REST API 文档 (UI)。

它的必要步骤或先决条件是什么？我正在使用 Windows 操作系统。

Answer 1

swagger-core是我们自己的用于与 JAX-RS 项目集成的库

我们提供 simple tutorial解释如何将其与您的代码集成。这是相当简单的。 annotations还记录在案，以帮助您了解应添加的内容和位置。

完成上述步骤后，您将获得 swagger.json 的输出。和 swagger.yaml文件。此时，您需要集成 swagger-ui与您的应用程序。有多种方法可以这样做。一种方法是将其与您的构建过程集成，就像我们在示例中所做的那样。

这两个插件的组合将为您做到:

  <plugin>
    <groupId>com.googlecode.maven-download-plugin</groupId>
    <artifactId>download-maven-plugin</artifactId>
    <version>1.2.1</version>
    <executions>
      <execution>
        <id>swagger-ui</id>
        <goals>
          <goal>wget</goal>
        </goals>
        <configuration>
          <url>https://github.com/swagger-api/swagger-ui/archive/master.tar.gz</url>
          <unpack>true</unpack>
          <outputDirectory>${project.build.directory}</outputDirectory>
        </configuration>
      </execution>
    </executions>
  </plugin>
  <plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <version>2.6</version>
    <executions>
      <execution>
        <id>copy-resources</id>
        <phase>validate</phase>
        <goals>
          <goal>copy-resources</goal>
        </goals>
        <configuration>
          <outputDirectory>target/${project.artifactId}-${project.version}</outputDirectory>
          <resources>
            <resource>
              <directory>${project.build.directory}/swagger-ui-master/dist</directory>
              <filtering>true</filtering>
              <excludes>
                <exclude>index.html</exclude>
              </excludes>
            </resource>
          </resources>
        </configuration>
      </execution>
    </executions>
  </plugin>

您只需要确保运行 package目标也是如此，比如 mvn package install如果你想安装它(但这取决于你的开发过程)。