Использование Javadocs для создания документа Swagger

Question

Я хочу создать документацию Swagger для существующего набора API RESTful. У меня есть следующее требование:

1. Генерация Swagger Doc в автономном режиме (я использовал http://kongchen.github.io/swagger-maven-plugin/). Этот плагин помогает мне генерировать документацию Swagger во время компиляции.
2. Чтение существующих 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, чтобы сэкономить время для моей команды?

Answer 1

Вы можете генерировать Swagger-UI из Javadoc с помощью Enunciate, который имеет модуль 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 и он будет генерировать файлы документации Swagger из вашего Javadoc.

Answer 2

SpringDoc теперь поддерживает создание документации Swagger из вашего JavaDoc, избавляя вас от бесконечного вырезания и вставки в ваших моделях.

https://github.com/springdoc/springdoc-openapi/issues/38https://github.com/springdoc/springdoc-openapi-maven-plugin

Answer 3

Кажется, есть документация Javadoc для генерации списка ресурсов JSON Swagger: https://github.com/teamcarma/swagger-jaxrs-doclet