ベースプロジェクトの作成¶

1. spring-initializrを利用してspring-bootのアプリケーションを作成します。

   

2. 利用するプロジェクトはサンプルの最低限の「spring web」としています。

   

3. spring-foxの依存関係を追加

   spring-bootと組み合わせて利用する場合の構成 以下を追加します。 （2022/05/18 時点の最新 3.0.0を利用）

   <dependency>
   	<groupId>io.springfox</groupId>
   	<artifactId>springfox-boot-starter</artifactId>
   	<version>3.0.0</version>
   </dependency>
   

4. Mainクラスにアノテーションを追加

   3.0.0を利用する場合には「spring-bootの起動用のmainクラス」に「@EnableWebMvc」を付与する必要があります。（付与しないとエラーで起動しなかった。）

   @EnableWebMvc
   @SpringBootApplication
   public class SpringFoxDemoApplication {
   
   	public static void main(String[] args) {
   		SpringApplication.run(SpringFoxDemoApplication.class, args);
   	}
   }
   

5. API用のControllerクラスの追加

   APIのドキュメントを出力するためのコントローラーを作成します。

   package jp.dip.snowsaber;
   
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestBody;
   import org.springframework.web.bind.annotation.RestController;
   
   /**
   * springfoxのサンプル用のControllerクラス
   * 
   */
   @RestController
   public class SpringFoxExampleController {
   
   	/**
   	* Postのサンプル
   	* 
   	* @param requestModel リクエスト
   	* @return レスポンスModel
   	*/
   	@PostMapping(value="/insert")
   	public ResponseModel insert(@RequestBody RequestModel requestModel) {
   		return new ResponseModel("テスト太郎", "xxxx@xxxx.xxxx");
   	}
   
   	/**
   	* リクエスト用のModel
   	* 
   	*/
   	public static class RequestModel {
   
   		/** ユーザID */
   		private String userId;
   
   		public String getUserId() {
   			return userId;
   		}
   
   		public void setUserId(String userId) {
   			this.userId = userId;
   		}
   
   
   	}
   
   	/** 
   	* レスポンス用のモデル
   	*/
   	public static class ResponseModel {
   
   		/** 名前 */
   		private String name;
   
   		/** アドレス */
   		private String addr;
   
   		public ResponseModel(String name, String addr) {
   			this.name = name;
   			this.addr = addr;
   		}
   
   		public String getName() {
   			return name;
   		}
   
   		public String getAddr() {
   			return addr;
   		}
   
   
   	}
   
   }
   

6. サンプルの起動

   コントローラを作成できたら早速起動し、swagger-uiの内容を確認します。 （2系の場合には追加で設定等が必要でしたが3系では依存関係を追加することで有効にすることができます。）

   springが正常に起動したら以下のURLにアクセスします。

   http://localhost:8080/swagger-ui/index.html

   URLにアクセスすると以下のような画面が表示されます。

   

   「spring-fox-example-controller」をクリックするとAPIの詳細が表示されます。

   

以上でサンプルの作成まで完了です。

API説明を付与(DocketのBeanへの登録)¶

API全体の説明等を記載する場合にはDocketをBeanとして登録することで表示されるようになります。

• SwaggerConfig

  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
  
  
  	@Bean
  	public Docket apiExample() {
  		return new Docket(DocumentationType.SWAGGER_2)
  				.apiInfo(apiInfo()) // アプリ情報を付与
  				;
  	}
  
  	/**
  	* アプリ情報の生成
  	* 
  	* @return アプリ情報
  	*/
  	private ApiInfo apiInfo() {
  		// タイトル
  		String title = "SpringFox Example API";
  		// 説明
  		String description = "SpringFoxの機能を確認するためのサンプルアプリケーション";
  		// バージョン
  		String version = "v2.0.0";
  		// 利用規約URL
  		String termsOfServiceUrl = "http://localhost:8080/dummy";
  		// 連絡先
  		String name = "連絡先名";
  		String url = "連絡先WebSiteURL";
  		String email = "連絡先メールアドレス";
  		Contact contact = new Contact(name, url, email);
  		// ライセンス
  		String license = "example-license";
  		// ライセンスURL
  		String licenseUrl = "http://localhost:8080/licenseUrl";
  		// 拡張用のドキュメント
  		Collection<VendorExtension> vendorExtensions = new ArrayList<>();
  		ApiInfo apiInfo = new ApiInfo(title, description, version, termsOfServiceUrl, contact, license, licenseUrl,
  				vendorExtensions);
  		return apiInfo;
  	}
  }
  

• 起動時の画面イメージ

  

• デフォルトのレスポンスコードを表示させないようにする場合

  「Docket」に対して「useDefaultResponseMessages」メソッドを利用しfalseを設定することでデフォルトのレスポンスコードを表示させないようにすることができます。

  @Bean
  public Docket apiExample() {
  	return new Docket(DocumentationType.SWAGGER_2)
  			.apiInfo(apiInfo()) // アプリ情報を付与
  			.useDefaultResponseMessages(true) // デフォルトのレスポンスコードのメッセージの追加有無
  			;
  }
  

  未設定時

  

  設定後

  

• 指定のURLのみ表示させるようにする場合

  Docketのselectメソッドを利用して生成される「ApiSelectorBuilder」のpathsメソッドを利用して絞り込みを実行します。

  @Bean
  public Docket apiExample() {
  	return new Docket(DocumentationType.SWAGGER_2)
  			.select()
  			.paths(assertTargetPath())	// 表示対象の絞り込み
  			.build()
  			.apiInfo(apiInfo()) // アプリ情報を付与
  			.useDefaultResponseMessages(false) // デフォルトのレスポンスコードのメッセージの追加有無  
  			;
  }
  // ～～ apiInfo メソッドは略 ～～～
  
  /**
  * 対象のPATHの絞り込み用のPredicateメソッド
  * 
  * @return 対象のPATHの絞り込み用のPredicate 
  */
  private Predicate<String> assertTargetPath() {
  	List<String> apiList = Arrays.asList("/insert");
  	return new Predicate<String>() {
  		@Override
  		public boolean test(String t) {
  			return apiList.contains(t);
  		}
  
  	};
  }
  

  未設定時

  

  設定時

  

個別の機能関連のアノテーション¶

• コントローラに説明を付与する（@Tag、@Api）

  TagアノテーションとApiアノテーションを組み合わせて利用することでコントローラ（API）の名称および説明を付与することができます。
  ※ Apiアノテーションにも説明（description）属性が用意されていますが非推奨となっているためTagアノテーションを利用します。

  /**
  * springfoxのサンプル用のControllerクラス
  * 
  */
  @RestController
  @Tag(name="検証用APIコントローラ", description = "コントローラ説明用")
  @Api(tags= "検証用APIコントローラ")
  public class SpringFoxExampleController {
  

  未設定時

  

  設定時

  

• API操作定義（@ApiOperation）

  /**
   * Postのサンプル
   * 
   * @param requestModel リクエスト
   * @return レスポンスModel
   */
  @PostMapping(value="/insert")
  @ApiOperation(value = "テスト用のリクエスト"
  		, notes = "springFox学習用のAPI "
  		+ "<br/>table構造は以下のように記載可能"
  		+ "<table  border=\"1\">"
  		+ "<tr><th>コード</th><th>備考</th></tr>"
  		+ "<tr><td>0000</td><td>成功時リクエスト</td></tr>"
  		+ "</table>")
  public ResponseModel insert(@RequestBody RequestModel requestModel) {
  	return new ResponseModel("テスト太郎", "xxxx@xxxx.xxxx");
  }
  

  • 実行時

  

• Apiで利用するModel（リクエスト・レスポンス共通）への設定（@ApiModelProperty）

  modelの説明を記載する場合は「@ApiModel」を利用します。

  /**
  * リクエスト用のModel
  *
  */
  @ApiModel(value = "検証用のリクエストModel")
  public class RequestModel {
  
  	/** ユーザID */
  	private String userId;
  
  	public String getUserId() {
  		return userId;
  	}
  
  	public void setUserId(String userId) {
  		this.userId = userId;
  	}
  }
  

  

• 個別要素への設定（@ApiModelProperty）

  リクエストの中身の要素に説明等を付与する場合には「ApiModelProperty」を利用します。

  /**
  * リクエスト用のModel
  *
  */
  @ApiModel(value = "検証用のリクエストModel")
  public class RequestModel {
  
  	/** ユーザID */
  	@ApiModelProperty(value="取得するユーザID", example = "0002")
  	private String userId;
  
  	public String getUserId() {
  		return userId;
  	}
  
  	public void setUserId(String userId) {
  		this.userId = userId;
  	}
  }
  

• 桁数等のサイズ情報を付与する場合

  @Min, @Max, @Size等を利用することでサイズ情報を付与することができます。

  pom.xmlに以下を追加

  <dependency>
  	<groupId>io.springfox</groupId>
  	<artifactId>springfox-bean-validators</artifactId>
  	<version>3.0.0</version>
  </dependency>	
  

  またアノテーション自体はSpringで利用しているものを追加するため以下の依存関係も追加します。

  <dependency>
  	<groupId>org.springframework.boot</groupId>
  	<artifactId>spring-boot-starter-validation</artifactId>
  </dependency>
  

  対象のモデルには@Sizeアノテーション等を付与します。

  /** ユーザID */
  @Size(min = 0, max = 4)
  @ApiModelProperty(value="取得するユーザID", example = "0002", required = true)
  private String userId;
  

  

  http://springfox.github.io/springfox/docs/current/#springfox-support-for-jsr-303

• 一部のvalueの値をプロパティ値から設定する場合

  application.propertites 等の設定値を利用して設定することも可能です。 例では「application.properties」にswaagerドキュメント用のファイルを追加し、追加したファイルに値を記載しています。

  application.properties

  spring.config.import=swagger-doc.yaml
  

  swagger-doc.yaml

  fd: 
  userId: 
  	name: ユーザID 	
  api:
  note: | 
  	springFox学習用のAPI 
  	table構造は以下のように記載可能
  	<table  border=\1\>
  	<tr><th>コード</th><th>備考</th></tr>
  	<tr><td>0000</td><td>成功時リクエスト</td></tr>
  	</table>		
  

  利用個所のjava

  /** ユーザID */
  @Size(min = 0, max = 4)
  @ApiModelProperty(value="${fd.userId.name}", example = "0002", required = true)
  private String userId;
  

  
  ※ 設定しても反映されない項目があります。
  例 ApiModelPropertyの example等
  http://springfox.github.io/springfox/docs/current/#property-file-lookup

その他メモ¶

• 環境変数等によるの無効化

  本番環境の場合にAPIを表示させたくない場合にはapplivcation.propertiesに以下のように設定することで無効化することができます。

  application.properties

  # springFoxの有効無効化
  springfox.documentation.enabled=${springfoxDocumentationEnabled:true}
  

参考サイト¶

• Spring Bootで作成したWEB APIにSwaggerを導入して簡単ドキュメント管理