1. 序章

この短いチュートリアルでは、APIを呼び出すときにJSON Web Token(JWT)を含めるようにSwaggerUIを構成する方法を説明します。

2. Mavenの依存関係

この例では、 springfox-boot-starter を使用します。これには、SwaggerおよびSwaggerUIの操作を開始するために必要なすべての依存関係が含まれています。 pom.xmlファイルに追加しましょう。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

3. Swagger構成

まず、 ApiKey を定義して、認証ヘッダーとしてJWTを含める必要があります。

private ApiKey apiKey() { 
    return new ApiKey("JWT", "Authorization", "header"); 
}

次に、グローバルAuthorizationScopeを使用してJWTSecurityContextを構成しましょう。

private SecurityContext securityContext() { 
    return SecurityContext.builder().securityReferences(defaultAuth()).build(); 
} 

private List<SecurityReference> defaultAuth() { 
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); 
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; 
    authorizationScopes[0] = authorizationScope; 
    return Arrays.asList(new SecurityReference("JWT", authorizationScopes)); 
}

次に、API Docket Beanを構成して、API情報、セキュリティコンテキスト、およびセキュリティスキームを含めます。

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .securityContexts(Arrays.asList(securityContext()))
      .securitySchemes(Arrays.asList(apiKey()))
      .select()
      .apis(RequestHandlerSelectors.any())
      .paths(PathSelectors.any())
      .build();
}
private ApiInfo apiInfo() {
    return new ApiInfo(
      "My REST API",
      "Some custom description of API.",
      "1.0",
      "Terms of service",
      new Contact("Sallo Szrajbman", "www.baeldung.com", "[email protected]"),
      "License of API",
      "API license URL",
      Collections.emptyList());
}

4. RESTコントローラー

ClientsRestController で、クライアントのリストを返す単純なgetClientsエンドポイントを記述しましょう。

@RestController(value = "/clients")
@Api( tags = "Clients")
public class ClientsRestController {

    @ApiOperation(value = "This method is used to get the clients.")
    @GetMapping
    public List<String> getClients() {
        return Arrays.asList("First Client", "Second Client");
    }
}

5. Swagger UI

これで、アプリケーションを起動すると、 http:// localhost:8080 / swagger-ui /URLでSwaggerUIにアクセスできます。

承認ボタンが付いたSwaggerUIを次に示します。

 

承認ボタンをクリックすると、SwaggerUIがJWTを要求します。

トークンを入力してAuthorizeをクリックするだけで、それ以降、APIに対して行われるすべてのリクエストで、HTTPヘッダーにトークンが自動的に含まれます。

 

6. JWTを使用したAPIリクエスト

APIにリクエストを送信すると、トークン値を含む「Authorization」ヘッダーがあることがわかります。

 

7. 結論

この記事では、Swagger UIがJWTをセットアップするためのカスタム構成を提供する方法を説明しました。これは、アプリケーションの承認を処理するときに役立ちます。 Swagger UIで承認すると、すべてのリクエストにJWTが自動的に含まれます。

この記事のソースコードは、GitHubからで入手できます。