Spring | Tech and Everyday Blog by masahosono

Spring | masahosono blog

データの登録をAPI経由で行うとき、作成日時や更新日時を対向APIやDBに連携する場面がある。複数APIが同じように日時を取り扱いたい場合、それぞれのAPIで日時オブジェクトを生成するのは冗長である。そのため、日時オブジェクトの生成を共通処理化してコントローラの引数としてバインドできるようにしてみた。


データの登録をAPI経由で行うとき、作成日時や更新日時を対向APIやDBに連携する場面がある。

複数APIが同じように日時を取り扱いたい場合、それぞれのAPIで日時オブジェクトを生成するのは冗長である。

そのため、日時オブジェクトの生成を共通処理化してコントローラの引数としてバインドできるようにしてみた。

## 環境
- Java 11
- Spring Boot 2.4.3

## 実装

Spring Frameworkでは、HandlerMethodArgumentResolverインタフェースを利用することで、任意のオブジェクトをバインドしてコントローラの引数として受け取ることができる。

### HandlerMethodArgumentResolverインタフェースの実装クラスを作成

`supportsParameter`メソッドは、コントローラのメソッドに指定した引数のオブジェクトがこのリゾルバで提供する型と同型であるか検証する。

`resolveArgument`メソッドは、リゾルバで提供するオブジェクトを返却する。

```java:RequestDateTimeHandlerMethodArgumentResolver.java
@Component
public class RequestDateTimeHandlerMethodArgumentResolver implements HandlerMethodArgumentResolver {

    private final Clock clock;

    public RequestDateTimeHandlerMethodArgumentResolver(Clock clock) {
        this.clock = clock;
    }

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.getParameterType().isAssignableFrom(RequestDateTime.class);
    }

    @Override
    public RequestDateTime resolveArgument(
            MethodParameter parameter,
            ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest,
            WebDataBinderFactory binderFactory) {
        return RequestDateTime.now(clock);
    }
}
```

```java:RequestDateTime.java
public class RequestDateTime {

    private final LocalDateTime value;

    public static RequestDateTime now(Clock clock) {
        return new RequestDateTime(LocalDateTime.now(clock));
    }

    public String format() {
        return value.format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));
    }

}
```

### WebMvcConfigurerインタフェースの実装クラスを作成

作成したリゾルバはそのままでは利用することができないので次のように設定する。

`addArgumentResolvers`メソッドは、リゾルバを適用するための設定を行う。

HandlerMethodArgumentResolverのリストを引数に取りうるので、DIしたリゾルバをリストの要素に追加してやれば良い。

```java:WebMvcConfigurerImpl.java
@Configuration
public class WebMvcConfigurerImpl implements WebMvcConfigurer {

    private final RequestDateTimeHandlerMethodArgumentResolver requestDateTimeHandlerMethodArgumentResolver;
    
    public WebMvcConfigurerImpl(RequestDateTimeHandlerMethodArgumentResolver requestDateTimeHandlerMethodArgumentResolver) {
        this.requestDateTimeHandlerMethodArgumentResolver = requestDateTimeHandlerMethodArgumentResolver;
    }

    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolverList) {
        resolverList.add(requestDateTimeHandlerMethodArgumentResolver);
    }
}
```

### コントローラのメソッドの引数として利用

RequestDateTimeを引数として受け取るためには次のように記載すれば良い。

```java:PostController.java
public ResponseEntity<RegisterPostResponse> registerPost(
        @RequestBody RegisterPostRequest requestBody,
        @Parameter(hidden = true) RequestDateTime requestDateTime) {
        
        System.out.println(requestDateTime.format()); // 20211021221245
       
       // 後続の処理は省略
}
```


Spring Frameworkでリクエスト日時をコントローラの引数として受け取る

Springdoc-openapiを使ってSpring Bootで実装したアプリケーションのAPI仕様書を実装コードから自動生成する。


[Springdoc-openapi](https://springdoc.org/)を使ってSpring Bootで実装したアプリケーションのAPI仕様書を実装コードから自動生成する。

API仕様書はIF部分に修正があるたびにメンテしてあげる必要があるが、メンテが疎かになると実装と乖離した内容となるため、実装コードベースで管理することで保守性が高まることを期待する。

また、springdoc-openapiにはSwagger UIでAPIドキュメントを表示することができる機能があるが、Redocが見た目的に好みなのでRedocで表示させる。

## 環境
- [Spring Boot](https://github.com/spring-projects/spring-boot) 2.3.10
- [springdoc-openapi](https://github.com/springdoc/springdoc-openapi) 1.5.9
- [Redoc](https://github.com/Redocly/redoc)

## 導入

### build.gradle
springdoc-openapi-uiを依存関係に追加
```java:build.gradle
dependencies {
    // 以下を追加
    implementation 'org.springdoc:springdoc-openapi-ui:1.5.10'
}

```

### Bean登録
OpenAPIのBeanを登録するための`OpenApiBeanConfiguration`クラスを新規追加する。
```java:OpenApiBeanConfiguration.java
import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiBeanConfiguration {

    @Bean
    public OpenAPI restApi() {
        return new OpenAPI();
    }
}
```

最低限動作させるための導入は上記作業で完了。

## 機能

### OpenAPIドキュメント取得
アプリケーションを起動して以下のエンドポイントにアクセスするとOpenAPIのドキュメントが取得できる。
json形式で取得：`/v3/api-docs`
yaml形式で取得：`/v3/api-docs.yaml`

### Swagger UIの表示
アプリケーションを起動して`/swagger-ui/index.html`にアクセスするとAPIドキュメントをSwagger UI上で表示できる。

## springdoc拡張設定
application.ymlにspringdocの各種設定を追加することができる。
```yaml:application.yml
springdoc:
  api-docs:
    path: /api-docs # デフォルトの/v3/api-docsのエンドポイントから任意のエンドポイントに変更。
  swagger-ui:
    enabled: false # Swagger UIの有効/無効の切り替え。
```

追加できるプロパティは公式ドキュメントを参照。
[Springdoc-openapi Properties](https://springdoc.org/#properties)


## OpenAPIドキュメントの拡張

OpenAPIが提供しているアノテーションを付与することで拡張が可能。
[OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#oasDocument)

### REST APIの情報を指定
`@Operation`アノテーションをControllerのメソッドに付与する。
APIのタイトルや概要説明の定義などが可能。
```java
@Operation(summary = "メモ取得API", description = "メモ情報の取得と返却を行う")
@GetMapping(path = "/memo", produces = "application/json")
public ResponseEntity<MemoResponse> getArticle() {}
```

### スキーマ定義の情報を指定
`@Schema`アノテーションをリクエスト/レスポンスのプロパティに付与する。
プロパティ名、サンプル値、最大最小値、初期値、必須可否、などの指定が可能。
```java
import io.swagger.v3.oas.annotations.media.Schema;

public class MemoResponse {

    @JsonProperty("title")
    @Schema(description = "メモタイトル", example = "タイトル1", required = true)
    private String title;

    @JsonProperty("text")
    @Schema(description = "メモ本文", example = "本文1")
    private String text;
}
```

## Redocで表示
spec-urlには、`/api-docs`のエンドポイントから取得したjsonを指定する。
```html:index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Redoc</title>
    <meta charset="utf-8"/>
    <meta name="robots" content="noindex, nofollow, noarchive"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
</head>
<body>
    <redoc spec-url="./api-docs.json"></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"> </script>
</body>
</html>
```

あとは任意のサービスで上記のhtmlを公開して共有するだけ。
チーム開発であればCI/CD処理でOpenAPIのドキュメントを吐き出して、GitHub Pagesで公開するのが良さそう。

Springdoc-openapiでAPIドキュメントを自動生成する

SpringのRestTemplateでは、プラス記号（＋）がエンコードされない。そのため、クエリパラメータにプラス記号が含まれているような外部APIに対してのリクエストで受け取る際に問題が生じてしまう。解決方法として、プラス記号は手動でエンコード（置換）やれば良い。


SpringのRestTemplateでは、プラス記号（＋）がエンコードされない。

そのため、クエリパラメータにプラス記号が含まれているような外部APIに対してのリクエストで受け取る際に問題が生じてしまう。

## 解決

リクエストURIに対してプラス記号をエンコード文字列に置換してやればよい。

今回は次のようなインターセプターで実装してみた。

```java:PlusSymbolEncodeInterceptor.java
@Component
public class PlusSymbolEncodeInterceptor implements ClientHttpRequestInterceptor {
    
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution) throws IOException {
        
        HttpRequest encodeRequest = new HttpRequestWrapper(request) {
            @Override
            public URI getURI() {
                return encodeUri(super.getRequest());
            }
        }
        
        return execution.execute(encodeRequest, body);
    }
    
    URI getUri(HttpRequest request) {
        URI uri = request.getURI();        
        return UriComponents.fromUri(uri)
                .replaceQuery(StringUtils.replace(uri.getRawQuery(), "+", "%2B")) // 「+」を「%2B」に置換
                .build(true)
                .toUri();
    }
}
```

あとは、RestTemplateBuilderなどを使ってインターセプターとして設定してやれば良い。

```java
RestTemplate restTemplate = restTemplateBuilder
    .additionalInterceptors(new PlusSymbolEncodeInterceptor());
    .build();
```

エンコードがされない特殊文字は他にもあるが同様の方法でエンコードしてやれば良い。