使用 Javadocs 生成 Swagger 文档

2022-01-22 00:00:00 swagger java maven swagger-maven-plugin

我想为现有的一组 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.

但是，我的问题是我是否可以使用 Javadocs 而不是让每个开发人员都创建 @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 从 Javadoc 生成 swagger-ui，它有一个 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.

相关文章