java 使用 Javadocs 生成 Swagger 文档
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/32340735/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Using Javadocs to generate Swagger document
提问by Raj
I want to build the Swagger documentation for an existing set of RESTful APIs. I have the following requirement:
我想为现有的一组 RESTful API 构建 Swagger 文档。我有以下要求：
- 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.
- Reading the existing Javadoc so that they can be used in the Swagger documentation.
- 离线生成 Swagger Doc（我使用了http://kongchen.github.io/swagger-maven-plugin/）。这个插件帮助我在编译时生成 Swagger 文档。
- 阅读现有的 Javadoc，以便它们可以在 Swagger 文档中使用。
So far using the above plugin I was able to achieve point no 1. So for an existing REST method:
到目前为止，使用上述插件我能够实现第 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 ) {
}
I was able to generate the Swagger documentation. The usage of @ApiOperation & @ApiResponses makes my documentation looks great.
我能够生成 Swagger 文档。@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?
但是，我的问题是我可以使用 Javadocs 而不是让每个开发人员都创建 @ApiOperation 和 @ApiResponses 以便为我的团队节省时间吗？
回答by Egemen
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.
您可以使用具有 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>
where 'enunciate.xml' contains your project specific configurations and looks like this:
其中 '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>
Then run mvn compileand it will generate Swagger documentation files from your Javadoc.
然后运行mvn compile，它将从您的 Javadoc 生成 Swagger 文档文件。
回答by dsavickas
There seems to be javadoc doclet for generating JSON Swagger resource listing: https://github.com/teamcarma/swagger-jaxrs-doclet
似乎有用于生成 JSON Swagger 资源列表的 javadoc doclet：https: //github.com/teamcarma/swagger-jaxrs-doclet
