既存のRESTful APIのセット用の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を使用すると、私のドキュメントが見栄えよくなります。
しかし、私の質問は、すべての開発者に@ApiOperationと@ApiResponsesを作成させるのではなく、Javadocを使用して、チームの時間を節約できるかどうかです。
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>
「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ドキュメントファイルが生成されます。
JSON Swaggerリソースリストを生成するためのjavadocドックレットがあるようです: https://github.com/teamcarma/swagger-jaxrs-doclet