使用Javadocs生成Swagger文档。

Question

使用Javadocs生成Swagger文档。

26

我想为一组现有的RESTful API构建Swagger文档，并有以下要求：

离线生成Swagger文档（我使用了http://kongchen.github.io/swagger-maven-plugin/插件）。该插件帮助我在编译时生成Swagger文档。
阅读现有的Javadoc，以便它们可以用于Swagger文档。

到目前为止，使用上述插件，我已经能够实现第1点。因此，对于现有的REST方法：

 /**
 * <p>
 * Gets the {@link DisplayPreferenceModel} with the name as provided in the parameter. The preference with the given name defined at the tenant or master level is returned.
 * This API gives us the preference if it is eligible for unauthorized access If it is not eligible it throws an Exception saying Authorization required.
 * </p>
 * @param preferenceName
 *            - The name of the preference.
 * @return {@link DisplayPreferenceModel}
 */
@RequestMapping(method = RequestMethod.GET, value = "/preferences/{preferenceName}")
@ApiOperation(value = "This API gives us the preference if it is eligible for unauthorized access If it is not eligible it throws an Exception saying Authorization required", 
                        notes = "No Notes please", response = DisplayPreferenceModel.class)
@ApiResponses(value = { 
                        @ApiResponse(code = 400, message = "Invalid preferenceName supplied"), 
                        @ApiResponse(code = 404, message = "Display Preference Not Found")
                      }
            )
public DisplayPreferenceModel getDisplayPreference( @PathVariable("preferenceName") final String preferenceName ) {
}

我能够生成 Swagger 文档。@ApiOperation 和 @ApiResponses 的使用使我的文档看起来很棒。

但是，我的问题是：我是否可以使用 Javadocs 来代替让每个开发人员创建 @ApiOperation 和 @ApiResponses，以便为我的团队节省时间？

- Raj

如何在 Maven 项目中生成 API 文档，@raj 你知道吗？我已经添加了 Api 和 ApiResonses 注解，但是如何生成文档呢？有什么帮助可以提供吗？ - Irfan Nasim

我使用了 'swagger-springmvc' v1.0.2。然后我创建了一个 CustomSwaggerConfig 类，其中包含 '@Configuration' 和 '@EnableSwagger'。在 applicationContext.xml 中，我引用了 CustomSwaggerConfig。 - Raj

我没有使用Spring，只是用Maven和Struts。 - Irfan Nasim

抱歉伙计，我在这方面帮不上你太多。我们的项目使用Spring库，因此我们使用“swagger-springmvc”。 - Raj

3个回答

2

SpringDoc 现在支持从你的 JavaDoc 生成 Swagger 文档，省去了在模型中无休止地复制粘贴的麻烦。

https://github.com/springdoc/springdoc-openapi/issues/38 https://github.com/springdoc/springdoc-openapi-maven-plugin

- dan carter

1

似乎有一个Javadoc Doclet用于生成JSON Swagger资源列表： https://github.com/teamcarma/swagger-jaxrs-doclet

- dsavickas

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Egemen · Accepted Answer

您可以使用 Enunciate 生成Swagger-UI文档，具体方法是使用该工具中的Swagger模块将Javadoc转换为Swagger-UI格式。首先需要在pom文件中添加Maven插件, 如下：

<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 compile，它将从你的Javadoc生成Swagger文档文件。