生成REST API文档的步骤

Question

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

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

Answer 1

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

我们提供了一个简单的教程来解释如何将它与代码集成.这很简单.该注释被记录为很好地帮助你了解什么应该被添加其中.

完成上述步骤后,您将获得一个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如果你想安装它(但这取决于你的开发过程).

Answer 2

Swagger提供了一些有关如何构建API文档的选项。

首先，您需要了解它分为两部分：

CORE用于生成包含有关API的相关信息的JSON。此JSON遵循swagger模板。

然后，INTERFACE将读取该JSON并生成HTML

首先，您将对控制器和端点进行注释，为此需要“ swagger-core”和“ swagger-annotations”。

然后，您有两个选择：

a）提供一个端点以生成和提供JSON，并使用swagger-ui读取该端点以生成HTML

b）在编译时使用maven插件swagger-maven生成JSON和HTML。

有关更多信息，请访问：

http://swagger.io/

https://github.com/swagger-api/swagger-spec#additional-libraries

如果您使用的是Spring，建议您访问https://github.com/springfox

如果您更喜欢Maven插件，请参见https://github.com/kongchen