使用Javadocs生成Swagger文档

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

1. 离线生成Swagger Doc（我使用了http://kongchen.github.io/swagger-maven-plugin/ ）。 这个插件帮助我在编译期间生成Swagger文档。
2. 读取现有的Javadoc，以便可以在Swagger文档中使用它们。

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

/** * 
 * 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. * 
 * @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，以便为我的团队节省时间吗？

Answer 1

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

  com.webcohesion.enunciate enunciate-maven-plugin ${enunciate.version}    docs   enunciate.xml ${project.build.directory}     

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

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

Answer 2

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