使用Javadocs生成Swagger文档 [英] Using Javadocs to generate Swagger document

问题描述

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

I want to build the Swagger documentation for an existing set of RESTful APIs. I have the following requirement:

1. 离线生成Swagger Doc（我使用 http://kongchen.github.io/swagger-maven-plugin/ ）。这个插件帮助我在编译期间生成Swagger文档。


2. 读取现有的Javadoc，以便它们可以在Swagger文档中使用。

1. Generate Swagger Doc offline (I used http://kongchen.github.io/swagger-maven-plugin/). This plugin helps me to generate the Swagger documentation during compile time.
2. Reading the existing Javadoc so that they can be used in the Swagger documentation.

到目前为止，使用上面的插件我能够达到第1点。所以对于现有的REST方法：

So far using the above plugin I was able to achieve point no 1. So for an existing REST method:

 /**
 * <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使我的文档看起来很棒。

I was able to generate the Swagger documentation. The usage of @ApiOperation & @ApiResponses makes my documentation looks great.

然而，我的问题是我可以使用Javadoc而不是让每个开发人员创建@ApiOperation& @ApiResponses以便为我的团队节省时间？

However, my question is can I use the Javadocs instead of making every developer to create @ApiOperation & @ApiResponses so that it saves time for my team?

推荐答案

您可以使用 Enunciate ，其中包含一个Swagger模块。首先，您需要将maven插件添加到您的pom文件中;例如。

You can generate swagger-ui from Javadoc by using Enunciate, which has a Swagger module. First, you need to add the maven plugin to your pom file; e.g.

<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'包含项目特定的配置，如下所示：

where 'enunciate.xml' contains your project specific configurations and looks like this:

<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文档文件。

Then run mvn compile and it will generate Swagger documentation files from your Javadoc.

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