首页 文章

使用Javadocs生成Swagger文档

提问于
浏览 次
15

我想为现有的一组RESTful API构建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的使用使我的文档看起来很棒 .

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

java maven swagger swagger-maven-plugin

2 回答

  • 0

    您可以使用带有Swagger模块的Enunciate从Javadoc生成swagger-ui . 首先，您需要将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 compile ，它将从您的Javadoc生成Swagger文档文件 .

    回复于
  • 12

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

    回复于

相关问题