JerseyベースのRESTサービスでREST APIドキュメントを生成するためのステップ
以下の環境を前提としています。
（ソースについては後日githubへpush予定）
dependenciesエレメントに下記のdependencyを追加してください。
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-jersey-jaxrs_2.10</artifactId>
<version>1.3.0</version>
</dependency>
2. web.xmlの編集
まずはjerseyのservletについて。
元々のservlet定義は
<servlet>
<servlet-name>Example Web Application</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>jp.gr.java_conf.ka_ka_xyz.example.service</param-value>
</init-param>
<init-param>
<param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Example Web Application</servlet-name>
<url-pattern>/service/*</url-pattern>
</servlet-mapping>
ですが、以下のように"com.sun.jersey.config.property.packages"にswaggerのパッケージ名を追加してください。
<servlet>
<servlet-name>Example Web Application</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>jp.gr.java_conf.ka_ka_xyz.example.service;com.wordnik.swagger.jersey.listing</param-value>
</init-param>
<init-param>
<param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Example Web Application</servlet-name>
<url-pattern>/service/*</url-pattern>
</servlet-mapping>
また、以下のservlet定義を追加してください。
<servlet>
<servlet-name>JerseyJaxrsConfig</servlet-name>
<servlet-class>com.wordnik.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
<init-param>
<param-name>api.version</param-name>
<param-value>1.0.0</param-value>
</init-param>
<init-param>
<param-name>swagger.api.basepath</param-name>
<param-value>http://localhost:8080/AngularjsWithSwagger/service</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
初期パラメータ"api.version"はREST APIバージョン、 "swagger.api.basepath"はREST APIのURLを指定します。
3. リソースクラスの編集
もともと、クラス自体に@Pathアノテーションが付いていましたが
@Path("/employee")
public class EmployeeService {
このようにjavax.ws.rs.Pathとcom.wordnik.swagger.annotations.Apiアノテーションを追加してください。
@Path("/employee")
@Produces(MediaType.APPLICATION_JSON)
@Api(value = "/employee", description = "社員に関するサービス")
public class EmployeeService {
また、もともとこんな感じでメソッドとURL・戻り値のMediaTypeを対応付けていましたが、
@GET
@Produces(MediaType.APPLICATION_JSON)
@Path("/all")
public List<Employee> getEmployees(){
以下のようにcom.wordnik.swagger.annotations.ApiOperation, com.wordnik.swagger.annotations.ApiResponses, com.wordnik.swagger.annotations.ApiResponseアノテーションを使ってREST APIドキュメント用の説明を書いてください。
@GET
@Produces(MediaType.APPLICATION_JSON)
@Path("/all")
@ApiOperation(value = "全ての社員情報を取得", notes = "条件指定せず、すべての社員情報を取得する", response = Employee.class)
@ApiResponses(value = {
@ApiResponse(code = 500, message = "サーバー内部エラー")
})
public List<Employee> getEmployees(){
4. モデルクラスの編集
もともとこんな感じでJax-RBアノテーションを使用してJSONとの対応付けていましたが
@XmlRootElement(name = "employee")
@XmlAccessorType(XmlAccessType.FIELD)
public class Employee implements Serializable{
内部的に使用されるUUID
@XmlAttribute
private String id;
一意な社員コード
@XmlAttribute
private String employeeCode;
以下のように、com.wordnik.swagger.annotations.ApiModel、 com.wordnik.swagger.annotations.ApiModelPropertyアノテーションを使ってREST APIドキュメント用の説明を書いてください。
@XmlRootElement(name = "employee")
@XmlAccessorType(XmlAccessType.FIELD)
@ApiModel(value = "社員情報")
public class Employee implements Serializable{
private static final long serialVersionUID = -7816174850279421158L;
内部的に使用されるUUID
@XmlAttribute
@ApiModelProperty(value = "内部的に使用されるUUID", required=true)
private String id;
一意な社員コード
@XmlAttribute
@ApiModelProperty(value = "社員コード", required=true)
private String employeeCode;
