Я хочу создать документацию Swagger для существующего набора RESTful API. У меня есть следующее требование:
- Создайте документ 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 моя документация выглядит великолепно.
Однако мой вопрос: могу ли я использовать Javadocs вместо того, чтобы заставлять каждого разработчика создавать @ApiOperation и @ApiResponses, чтобы сэкономить время моей команде?
