生成 REST API 文档

Question

有没有办法自动生成我的 Jersey Rest Services 的ZOHO 样式文档？这是迄今为止我见过的最好的 REST 文档之一。我对替代品持开放态度。

Swagger 看起来也很有希望，但我不知道如何生成它。似乎它需要一个 YAML 样式的文档。

我能以某种方式从 javadoc 生成它吗？

我更喜欢通过 Maven 生成文档。

Answer 1

将 swagger 添加到基于球衣的服务并不太复杂。 请参阅这些详细的steps 了解如何操作：

希望有帮助

Answer 2

您可以使用 Enunciate 从 Javadoc 生成 swagger-ui，它有一个 Swagger 模块。首先，您需要将 maven 插件添加到您的 pom 文件中；例如

<plugin>
        <groupId>com.webcohesion.enunciate</groupId>
        <artifactId>enunciate-maven-plugin</artifactId>
        <version>${enunciate.version}</version>
        <executions>
           <execution>
                  <goals>
                    <goal>docs</goal>
                  </goals>
                  <configuration>
                    <configFile>enunciate.xml</configFile>
                    <docsDir>${project.build.directory}</docsDir>
                  </configuration>
           </execution>
        </executions>
</plugin>

其中 'enunciate.xml' 包含您的项目特定配置，如下所示：

<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.0.0-M.3.xsd">

    <application root="/rest" />

</enunciate>

然后运行mvn package，它将从您的 Javadoc 生成 Swagger 文档文件。

附言取自我的回答here。

Answer 3

您可以使用Swagger 记录您的 REST API，设置起来并不难。有一些说明here。总结一下：

添加 Swagger 依赖项

将以下依赖项添加到您的pom.xml：

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jersey2-jaxrs</artifactId>
    <version>1.5.0</version>
</dependency>

设置 Swagger

将以下内容添加到您的 Application 类中（根据您的需要更改值）：

@ApplicationPath("/api")
public class MyApplication extends Application {

    public MyApplication() {
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0");
        beanConfig.setSchemes(new String[]{"http"});
        beanConfig.setHost("localhost:8080");
        beanConfig.setBasePath("/api");
        beanConfig.setResourcePackage("io.swagger.resources,com.example.project");
        beanConfig.setScan(true);
    }
}

构建您的项目，启动您的服务器并访问 http://localhost:8080/app/api/swagger.json（您的环境中的 URL 可能不同）以获取记录您的 API 的 JSON。

设置 Swagger 用户界面

从 GitHub 下载 Swagger UI，并将 dist 文件夹中的内容复制到您的 Web 内容文件夹。我通常会创建一个名为 api-docs 的文件夹来存储所有 Swagger UI 文件。

打开 Swagger UI 的 index.html 并更改引用 swagger.json 的 URL：

var swaggerUi = new SwaggerUi({
    url: "http://localhost:8080/app/api/swagger.json",
    dom_id: "swagger-ui-container"
});

访问http://localhost:8080/app/api-docs（您的环境中的 URL 可能不同）。带有 API 文档的 Swagger UI 应该在那里。

更多信息

• 您随时可以customize Swagger UI 来满足您的需求。

• Swagger 读取 JAX-RS annotations 以生成文档。此外，您可以使用Swagger annotations 对其进行改进。