我想为一组现有的 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 的使用使我的文档看起来很棒。
但是,我的问题是我可以使用 Javadoc 而不是让每个开发人员创建 @ApiOperation 和 @ApiResponses 以便为我的团队节省时间吗?
最佳答案
您可以使用 Enunciate 从 Javadoc 生成 swagger-ui ,它有一个 Swagger 模块。首先,您需要将 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 文档文件。
关于java - 使用Javadocs生成Swagger文档,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/32340735/