生成REST API文档 [英] Generate REST API documentation

问题描述

有没有办法自动生成 ZOHO 风格的文档我的泽西休息服务？这是迄今为止我见过的最好的REST文档之一。我愿意接受替代方案。

Is there a way to auto-generate a ZOHO-style documentation of my Jersey Rest Services? This is one of the best REST documentations I have seen so far. I'm open to alternatives.

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

Swagger also looks promising but I don't see how to generate it. It seems like it needs a YAML style documentation.

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

Can I generate it from javadoc somehow?

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

I'd prefer to generate the docs via Maven.

推荐答案

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

You can use Swagger to document your REST API, it's not difficult to set up. There are some instructions here. To summarize:

将以下依赖项添加到 pom。 xml ：

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

设置Swagger

添加以下内容到你的 申请 class（根据您的需要更改值）：

Setting up Swagger

Add the following to your Application class (change the values according to your needs):

@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。

Build your project, start your server and access http://localhost:8080/app/api/swagger.json (the URL might be different in your environment) to get the JSON which documents your API.

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

Download Swagger UI from GitHub and copy the content from the dist folder to your web content folder. I usually create a folder called api-docs to store all Swagger UI files.

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

Open Swagger UI's index.html and change the URL which refers to the swagger.json:

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应该在那里。

Access http://localhost:8080/app/api-docs (the URL might be different in your environment). The Swagger UI with your API documentation should be there.

• 您始终可以自定义Swagger UI 以满足您的需求。

Swagger读取 JAX-RS注释以生成文档。此外，您可以使用 Swagger注释改善它。

Swagger reads JAX-RS annotations to generate the documentation. Additionally, you can use Swagger annotations to improve it.

这篇关于生成REST API文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！