masahosono blog

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();
```

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

SpringのRestTemplateでプラス記号をエンコードする

macOSのターミナルを快適に使うためにzshの設定周りを試行錯誤した。ただし、派手なターミナルはあまり好みではないのでシンプルに表示できるようにしてみた。


macOSのターミナルを快適に使うためにzshの設定周りを試行錯誤した。

ただし、派手なターミナルはあまり好みではないのでシンプルに表示できるようにしてみた。

## プロンプト表示

デフォルトのプロンプト表示は次の形式であるため、ユーザ名やホスト名（マシン名）が長い場合、かなり冗長に表示されてしまう。

また、linuxの用にユーザーログインを頻繁に繰り返すわけではないため、ユーザ名やホスト名が表示されていても嬉しいことは殆どない。

```bash
[username]@[hostname] ~ %
```

個人的には、現在時刻とカレントディレクトリがプロンプトに表示されていれば必要十分と感じている。

現在時刻とカレントディレクトリを表示するようなプロンプトの設定は次のとおり。

```
PROMPT="%* %~ $ "
```

ターミナル上の表示は次のようになる。

```bash
22:23:39 ~ $
```

## プロンプト表示（Git）

GitはCLI上で操作することが多いので、プロンプトにGitのカレントブランチの情報を表示させたい。

vcs_infoを読みこんだうえで各種設定を記述する。

修正がステージングエリアに追加されているか否かで表示色の切り替えなども可能。

```bash
autoload -Uz vcs_info
setopt prompt_subst
zstyle ':vcs_info:git:*' check-for-changes true
zstyle ':vcs_info:git:*' stagedstr "%F{yellow}!"
zstyle ':vcs_info:git:*' unstagedstr "%F{red}+"
zstyle ':vcs_info:*' formats "%F{green}%c%u[%b]%f"
zstyle ':vcs_info:*' actionformats '[%b|%a]'
precmd () { vcs_info }
RPROMPT=$RPROMPT'${vcs_info_msg_0_}'
```

ターミナル上の表示は次のようになる。

```bash
22:23:39 ~/Project/hoge $                                                                             !+[master]

```


## ヒストリーの保存場所と記録サイズ

macOSの場合、コマンド履歴がデフォルトで最大500件までしか残らない。

500件だとさすがに少ないので、10万件程度に増やしておきたい。

そのため、HISTSIZEとSAVEHISTの設定値をそれぞれ10万件に設定する。

```
HISTFILE=~/.zsh_history
HISTSIZE=100000
SAVEHIST=100000
```

## 補完
zshの補完機能はbashなどに比べて強力であるがデフォルトでは無効になっている。

有効にするにはcompinitを読み込んだ上で実行させてあげれば良い。

```bash
autoload -Uz compinit
compinit
```

## まとめ

現在利用しているzshの設定の全体像は次のとおり。

使える部分があれば是非参考にしてみてください。

```:.zshrc
autoload -Uz compinit
compinit

PROMPT="%* %~ $ "

# 明示的なcdコマンドが不要となる
setopt auto_cd

# cdコマンドの途中でTabキーを押下すると、ディレクトリの履歴を表示
setopt auto_pushd

# コマンドのタイポが指摘される
setopt correct

# ヒストリーの保存場所と記録サイズ
HISTFILE=~/.zsh_history
HISTSIZE=100000
SAVEHIST=100000

# ヒストリーの補完
bindkey "^P" history-beginning-search-backward
bindkey "^N" history-beginning-search-forward

# git
autoload -Uz vcs_info
setopt prompt_subst
zstyle ':vcs_info:git:*' check-for-changes true
zstyle ':vcs_info:git:*' stagedstr "%F{yellow}!"
zstyle ':vcs_info:git:*' unstagedstr "%F{red}+"
zstyle ':vcs_info:*' formats "%F{green}%c%u[%b]%f"
zstyle ':vcs_info:*' actionformats '[%b|%a]'
precmd () { vcs_info }
RPROMPT=$RPROMPT'${vcs_info_msg_0_}'

# alias
alias ssh='ssh -o ServerAliveInterval=60'
export PATH="/usr/local/opt/mysql@5.7/bin:$PATH"

# env
export SPRING_DATASOURCE_URL=jdbc:mysql://localhost:3306/****
export SPRING_DATASOURCE_USERNAME=root
export SPRING_DATASOURCE_PASSWORD=******
export PATH="/usr/local/opt/mongodb-community@4.4/bin:$PATH"

# Java
export JAVA_HOME=`/usr/libexec/java_home -v "17"`
PATH=${JAVA_HOME}/bin:${PATH}
```

macOSのzshの設定を個人的に使いやすいようにカスタマイズした

データベースにはRDBMSとRDBMS以外のNoSQLがあるが、NoSQLは今まで使ったことがなかったので触れてみる。そこで、NoSQLデータベースの中でも比較的人気なMongoDBを導入して試してみた。


データベースにはRDBMSとRDBMS以外のNoSQLがあるが、NoSQLは今まで使ったことがなかったので使ってみた。

NoSQLデータベースの中でも比較的人気なMongoDBを導入した。

## NoSQLとは

RDBMSがリレーショナルモデルで管理するデータベースであるのに対して、NoSQLはリレーショナルモデルを用いない。

NoSQLは以下の分類に分けられる。
- キー・バリュー型： キーとバリューだけの単純な構造のデータベース。
- カラム指向型： キー・バリューがカラムによってグループ化されているデータベース。
- ドキュメント指向型： JSONやXMLといったドキュメントで管理するデータベース。
- グラフ指向型： ノード間の関係を管理するデータベース。

## MongoDBとは
MongoDBはドキュメント指向型に分類され、BSON（バイナリ型JSON）と呼ばれるデータフォーマットを利用している。

複数のBSONはコレクションと呼ばれる単位で管理される。

扱うデータの種別によって、RDBMSに比べCRUD処理を高速に行えるメリットがある。

## 環境
* [MongoDB](https://www.mongodb.com) v4.4.13

## 導入

### インストール

[公式のインストール手順](https://www.mongodb.com/docs/manual/installation/)に沿ってインストールしていく。

```shell
$ brew tap mongodb/brew
$ brew update
$ brew install mongodb-community@4.4
```

パスを通す。
```shell
$ echo 'export PATH="/usr/local/opt/mongodb-community@4.4/bin:$PATH"' >> ~/.zshrc
```

Macのシステム起動時に自動起動させたい場合は、Homebrewのサービスに設定しておく。
```shell
$ brew services start mongodb/brew/mongodb-community@4.4
```

## 使い方

### シェルの起動
```shell
$ mongo
MongoDB shell version v4.4.13
connecting to: mongodb://127.0.0.1:27017/?compressors=disabled&gssapiServiceName=mongodb
Implicit session: session { "id" : UUID("hoge") }
MongoDB server version: 4.4.13
> 
```

MongoDBはデフォルトポート27017で立ち上がる。

### データベースの作成/切り替え
```shell
> use blog
switched to db blog
```

### データベースの状態
```shell
> db.stats()
{
        "db" : "blog",
        "collections" : 0,
        "views" : 0,
        "objects" : 0,
        "avgObjSize" : 0,
        "dataSize" : 0,
        "storageSize" : 0,
        "totalSize" : 0,
        "indexes" : 0,
        "indexSize" : 0,
        "scaleFactor" : 1,
        "fileSize" : 0,
        "fsUsedSize" : 0,
        "fsTotalSize" : 0,
        "ok" : 1
}
```

### コレクション（テーブル）作成
```shell
> db.createCollection('posts');
{ "ok" : 1 }
```

### ドキュメント（レコード）追加
```shell
> db.posts.insert({ title: 'テスト記事', text: 'テスト記事の本文' });
WriteResult({ "nInserted" : 1 })
```

### ドキュメント（レコード）取得
MongoDBでは、_idが主キーとして扱われる。
```shell
> db.posts.find({_id: ObjectId("626533b0dda7edc966d8f1e0")});
{ "_id" : ObjectId("626533b0dda7edc966d8f1e0"), "title" : "テスト記事", "text" : "テスト記事の本文" }
```

### ドキュメント（レコード）更新
updateの第1引数が検索条件、第2引数が更新内容となる。
```shell
> db.posts.update({_id: ObjectId("626533b0dda7edc966d8f1e0")}, { title: 'テスト記事_更新', text: 'テスト記事の本文_更新' });
```

### ドキュメント（レコード）削除
```shell
> db.posts.remove({_id: ObjectId("626533b0dda7edc966d8f1e0")});
```

MongoDBを導入する

Next.jsで外部のAPIに対して非同期でリクエストをしたところCORSエラーが発生した。異なるオリジン間での通信を許可するにはサーバ側にリソース共有を許可する設定を導入する手法が一般的だが、今回はクライアント側だけで対応してみた。そこで、http-proxy-middlewareというモジュールを使ってHTTPリクエストをプロキシすることでエラー回避をしてみた。


Next.jsで外部のAPIに対して非同期でリクエストをしたところCORSエラーが発生した。

異なるオリジン間での通信を許可するにはサーバ側にリソース共有を許可する設定を導入する手法が一般的だが、今回はクライアント側だけで対応してみた。

そこで、[http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)というモジュールを使ってHTTPリクエストをプロキシすることでエラー回避をしてみた。

## 環境
* [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware) 1.0.6
* [Next.js](https://www.npmjs.com/package/next) 10.0.3
* [Express](https://github.com/expressjs/express) 4.17.1

## 導入
```shell
$ yarn add http-proxy-middleware
```

http-proxy-middlewareはミドルウェアとして提供されているので、他のフレームワークと組み合わせる必要がある。
今回はExpressのミドルウェア関数として導入してみた。

```javascript:server.js
const express = require('express');
const next = require('next');
const {createProxyMiddleware} = require('http-proxy-middleware');

const dev = process.env.NODE_ENV !== 'production';
const port = process.env.PORT || 3000;

const app = next({ dev });
const handler = app.getRequestHandler();
const server = express();

app.prepare()
    .then(() => {
        server.use(['/api'], createProxyMiddleware({
                target: "http://localhost:3001", // プロキシ対象のホスト
                changeOrigin: true,
            })
        )

        server.all('*', (req, res) => {
            return handler(req, res)
        });

        server.listen(port, () => {
            console.debug(`> Runnning on http://localhost:${port}`)
        })
    })
    .catch(() => {
        console.error()
        process.exit(1)
    })
```


上記のプロキシの設定は、APIを提供しているサーバをlocalhostの3001番ポートで起動した場合を想定している。

APIのサーバでは、`http:localhost:3001/api/hoge`のエンドポイントでAPIを提供する。

http-proxy-middlewareを導入したことで`http:localhost:3000/api/hoge`にリクエストすると、APIサーバへとプロキシされる。
```shell
$ curl localhost:3000/api/hoge
{
    success: true,
    body: {},
}
```


Next.jsでAPIリクエストをproxyする

Next.jsのアプリケーションよりも上位のレイヤに独自処理を挟みたかっため、Next.jsのカスタムサーバとしてExpressを導入して機能の拡張を行った。


Next.jsでアプリケーションを構築したときに次のような機能が欲しいことがあった。

- pagesディレクトリ以外でのルーティングの構築
- アプリケーションよりも上位のレイヤに独自処理を挟む

これらの機能は、Next.jsのアプリケーションよりも上位で実行させる必要があるため、Next.js単体だと実現させるのが難しかった。

そこで、Next.jsのカスタムサーバとしてExpressを導入して機能の拡張を行った。

## 環境
* [Next.js](https://www.npmjs.com/package/next) 10.0.3
* [Express](https://github.com/expressjs/express) 4.17.1

## 導入

```shell
$ yarn add express
```

カスタムサーバの実行スクリプトを作成。

```javascript:server.js
const express = require('express');
const next = require('next');

const dev = process.env.NODE_ENV !== 'production';
const port = process.env.PORT || 3000;

const app = next({ dev });
const handler = app.getRequestHandler();
const server = express();

app.prepare()
    .then(() => {
        server.all('*', (req, res) => {
            return handler(req, res)
        });

        server.listen(port);
    })
    .catch(() => {
        console.error()
        process.exit(1)
    })
```

作成したファイルをNode.jsで実行するとExpressでHTTPサーバが起動する。
```shell
$ node server.js
```

Next.jsを開発モードで起動する場合は、NextServerのインスタンス（app）を生成する際にtrueを指定する。

実行環境は環境変数で切り替えられるようにして、次のようなスクリプトで指定できるようにした。

```javascript:package.json
"scripts": {
  "start:dev": "node server.js",
  "start:prod": "NODE_ENV=production node server.js"
}
```

### 静的ファイルのディレクトリを変更

Next.jsにおける静的ファイルの公開は、publicディレクトリが公開対象となるが、Expressを組み合わせることで公開ディレクトリを追加することができる。
https://expressjs.com/ja/starter/static-files.html

```javascript:server.js
import express from 'express'
import next from 'next'

const dev = process.env.NODE_ENV !== 'production';
const port = process.env.PORT || 3000;

const app = next({ dev });
const handler = app.getRequestHandler();
const server = express();

app.prepare()
    .then(() => {
        server.use('/static', express.static('static')); // staticディレクトリを公開ディクレトリに追加

        server.all('*', (req, res) => {
            return handler(req, res)
        });

        server.listen(port, () => {
            console.debug(`> Running on http://localhost:${port}`);
        })
    })
    .catch(() => {
        console.error()
        process.exit(1)
    })
```

### 独自処理の挿入
Expressでは必要に応じてミドルウェアを追加することで機能を拡張することができる。
https://expressjs.com/ja/guide/using-middleware.html

ここでは、例として管理者ページ（/admin）へアクセスされたときにユーザ認証を行う場合を想定とした処理を記載。

```javascript:server.js
import express, {NextFunction, Request} from 'express'
import next from 'next'

// server
const dev = process.env.NODE_ENV !== 'production'
const port = process.env.PORT || 3000;

const app = next({ dev })
const handler = app.getRequestHandler()
const server = express()

// ミドルウェア（auth）を定義
const auth = (req, res, next) => {
    const hasError = false; // 略（独自の認証処理 ex.JWT）
    if (hasError) {
        return next(res.status(401));
    }
    next();
}

app.prepare()
    .then(() => {
        // ミドルウェアの定義
        server.use((req, res, next) => {
            console.debug(`[${req.url}]`, `[${req.method}]`, 'Request Received')
            next()
        })

        // ミドルウェア（auth）を挿入
        server.get('/admin', auth, (req, res, next) => {
            return handler(req, res);
        })

        server.all('*', (req, res) => {
            return handler(req, res);
        })

        server.listen(port, () => {
            console.debug(`> Running on http://localhost:${port}`);
        })
    })
    .catch(() => {
        console.error()
        process.exit(1)
    })
```

このように記載することでNext.js側でルーティングされる前に任意の処理を挟むことができる。


Next.jsのカスタムサーバとしてExpressを利用する

markedというライブラリを使ってマークダウン記法の文字列をHTMLに変換して表示させてみた。また、コードブロック内のコードはハイライト表示にさせたかったのでhighlightjsというライブラリも併用して使ってみた。


[marked](https://github.com/markedjs/marked)ライブラリでマークダウン記法の文字列をHTMLに変換して表示させてみた。
また、コードブロック内のコードはハイライト表示させたかったので、[highlightjs](https://github.com/highlightjs/highlight.js)ライブラリもmarkedと組み合わせて利用した

## 環境
* [React](https://github.com/facebook/react) v16.13.1
* [marked](https://github.com/markedjs/marked) v1.2.5
* [highlightjs](https://github.com/highlightjs/highlight.js) v9.16.2

## 導入
```shell
$ yarn add marked
$ yarn add highlightjs
```

marked関数にマークダウン記法の文字列を渡すとHTMLが返却される。
```javascript:index.ts
import React from 'react';
import marked from "marked";``

const Marked = () => {
    const markdownString =
        "# Header \n" +
        "**Bold** \n\n" +
        "[Google](https://www.google.com/)";

    return marked(markdownString);
}
export default Marked;
```

変換後のHTMLは以下のとおり
```html
<h1 id="header">Header</h1> 
<p><strong>Bold</strong></p> 
<p><a href="https://www.google.com/">Google</a></p>
```

### 画面表示
dangerouslySetInnerHTMLなどを使いHTMLを画面表示させる。
```javascript:index.ts
import React from 'react';
import marked from "marked";

const Marked = () => {
    const markdownString =
        "# Header \n" +
        "**Bold** \n\n" +
        "[Google](https://www.google.com/)";

    return <div dangerouslySetInnerHTML={{__html: marked(markdownString)}}/>;
}
export default Marked;
```

起動してブラウザを開くとHTMLに展開されて表示される。

![img.png](img.png)

### コードをハイライト表示

ハイライト表示するにはhighlightjsにコードブロック内のソースコードを構文解析させてHTMLに変換させる必要がある。

marked関数の第2引数には[オプション](http://adilapapaya.com/docs/marked/#options)が指定でき、highlightオプションを使うとコードブロックの内容に対して独自処理を挟むことが可能。

また、適用するcssはimportしておく。cssのテーマの一覧は[highlight.jsのデモページ](https://highlightjs.org/static/demo/)で確認することができる。

```javascript:index.ts
import React from 'react';
import marked from "marked";
import highlight from 'highlightjs'
import 'highlightjs/styles/a11y-dark.css' // 適用するテーマを指定

const Marked = () => {
    const markdownString =
        "```javascript\n" + // コードブロック内のコードの言語を指定
        "import React from \"react\";\n" +
        "import SimpleMDE from \"react-simplemde-editor\";\n" +
        "import \"easymde/dist/easymde.min.css\";\n" +
        "\n" +
        "const MarkdownEditor = () => {\n" +
        "    return <SimpleMDE id=\"simple-mde\" />;\n" +
        "}\n" +
        "export default MarkdownEditor\n" +
        "```";

    const markedOptions = {
        highlight: (code: string, lang: string) => {
            return (
                '<code class="hljs">' + highlight.highlightAuto(code, [lang]).value + '</code>'
            );
        }
    };

    return <div dangerouslySetInnerHTML={{
        __html: marked(markdownString, markedOptions) // 第2引数にオプションを指定
    }}/>;
export default Marked;
```

ハイライト結果は以下のとおり。

![img_2.png](img_1.png)