SpringBootでSwaggerドキュメントからエンドポイントを非表示にする

投稿日: 2022-10-12 2022-10-12
タグ: REST, Spring Boot, Spring Web, Swagger

1. 概要

Swaggerドキュメントを作成する際、エンドユーザーがエンドユーザーに公開されないようにエンドポイントを非表示にする必要があることがよくあります。これを行う最も一般的なシナリオは、エンドポイントの準備がまだ整っていない場合です。また、公開したくないプライベートエンドポイントがいくつかある可能性もあります。

この短い記事では、SwaggerAPIドキュメントからエンドポイントを非表示にする方法を説明します。これを実現するために、コントローラークラスでアノテーションを使用します。

2. @ApiIgnoreでエンドポイントを非表示にする

@ApiIgnoreアノテーションを使用すると、エンドポイントを非表示にできます。コントローラのエンドポイントに次のアノテーションを追加しましょう。

@ApiIgnore
@ApiOperation(value = "This method is used to get the author name.")
@GetMapping("/getAuthor")
public String getAuthor() {
    return "Umang Budhwar";
}

3. @ApiOperationでエンドポイントを非表示にする

または、 @ApiOperationを使用して、単一のエンドポイントを非表示にすることもできます。

@ApiOperation(value = "This method is used to get the current date.", hidden = true)
@GetMapping("/getDate")
public LocalDate getDate() {
    return LocalDate.now();
}

Swaggerがこのエンドポイントを無視するようにするには、hiddenプロパティをtrueに設定する必要があることに注意してください。

4. @ApiIgnoreですべてのエンドポイントを非表示にする

それでも、コントローラークラスのすべてのエンドポイントを非表示にする必要がある場合があります。これは、コントローラークラスに@ApiIgnoreでアノテーションを付けることで実現できます。

@ApiIgnore
@RestController
public class RegularRestController {
    // regular code
}

これにより、コントローラー自体がドキュメントから非表示になることに注意してください。

6. @Hiddenでエンドポイントを非表示にする

OpenAPI v3 を使用している場合、@Hiddenアノテーションを使用してエンドポイントを非表示にできます。

@Hidden
@GetMapping("/getAuthor")
public String getAuthor() {
    return "Umang Budhwar";
}

7. @Hiddenですべてのエンドポイントを非表示にする

同様に、コントローラーに @Hidden の注釈を付けて、すべてのエンドポイントを非表示にすることができます。

@Hidden
@RestController
public class RegularRestController {
    // regular code
}

これにより、コントローラーもドキュメントから非表示になります。

注：OpenAPIを使用している場合は、@Hiddenのみを使用できます。 Swaggerv3でのこの注釈のサポートはまだ進行中です。

8. 結論

このチュートリアルでは、Swaggerのドキュメントからエンドポイントを非表示にする方法を説明しました。単一のエンドポイントと、コントローラークラスのすべてのエンドポイントを非表示にする方法について説明しました。

いつものように、Swaggerの例の完全なコードはGitHubで利用でき、OpenAPIv3の例はGitHubでも利用できます。

getdocs

13036