このエントリーをはてなブックマークに追加

spring-foxを利用したswagger-uiの利用

作成日: 2022/05/18

springアプリケーションを利用する際にswaggerを利用してAPI用のドキュメントを作成するためのライブラリのspring-foxを利用する際のメモ

公式サイト:http://springfox.github.io/springfox/

作成した資材については以下にて公開

github

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

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

    ../../_images/0011.png

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

    ../../_images/0021.png

  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にアクセスすると以下のような画面が表示されます。

    ../../_images/003.png

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

    ../../_images/0041.png

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

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;
    	}
    }
    
  • 起動時の画面イメージ

    ../../_images/0051.png

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

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

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

    未設定時

    ../../_images/007.png

    設定後

    ../../_images/008.png

  • 指定の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);
    		}
    
    	};
    }
    

    未設定時

    ../../_images/010.png

    設定時

    ../../_images/011.png

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

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

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

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

    未設定時

    ../../_images/012.png

    設定時

    ../../_images/013.png

  • 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");
    }
    
    • 実行時

    ../../_images/006.png

  • 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;
    	}
    }
    

    ../../_images/009.png

  • 個別要素への設定(@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;
    

    ../../_images/014.png

    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}