1.前回記事
前回記事はこちらです。
システム開発時の詳細設計書系ついて①（画面設計書について）
https://qiita.com/yu-F/items/1b7510d6f43707b09535
システム開発時の詳細設計書系ついて②（ ビジネスルールについて）
https://qiita.com/yu-F/items/7c9323d1f6c8121f8bf0
詳細設計書としての必要な資料一式について
① 画面設計書（画面のレイアウト＋部品の説明＋DBの付き合わせ）
② 画面に対してのビジネスルール
③ API設計書
④ OpenAPIを使用してのSwagger EditorのIF設計書
今回は「③ API設計書」について書きます。
2.各資料の役割について（画面に対してのビジネスルール）
今回は列に並べて連動させて書いていきます。
私が作成するAPIについては基本、BFF→BEを呼び出す経路にし、BEで必要なテーブルの全カラムのDTOを取得して、テーブル単位で
組み合わせたレスポンスを返して、BFF側で必要な情報だけに絞って、呼び出し側へレスポンスで返すイメージです。
1. No
→BFFの項番を記載する。
2. BFF
画面から直接呼ばれるAPIとなります。
大元のIFとなり、ここへのパラメータの受け渡しが画面から受け取るものや画面へ反映する値の重要なものになります。
2.1 API名
→BFFのAPI名となります。BEのAPI名と重複するのは問題ないですが、BFF一覧内でのAPI名は一意とします。
2.2 通信方法
→ 記載観点として、取得であれば、GET、更新系であれば、POST、PUTのいずれか（推奨はPOST)
2.3 パラメータ
→「2.2 通信方法」において、GETであれば、ここにパスパラメータまたはクエリパラメータで連携する値をパラメータとして記載する。
→ 記載観点として、取得時にキーとなる項目がメインとして渡されることが想定される。
→ 記載方法としてはパラメータの物理名を行単位で箇条書きで書いていくのみ。
2.3 リクエスト
→「2.2 通信方法」において、POST(PUT)であれば、ここに、BFFへのリクエストボディのパラメータを記載します。
→ 記載観点として、画面へ入力や設定された更新や登録に必要な情報を一括でリクエストボディに設定されて渡される想定。
→ システム日付やバックエンド側で取得できる内容は画面からはあまり渡されないようにする。
2.3 レスポンス
→「2.2 通信方法」の内容に関わらず、記載すること。
→ 記載観点として、 BEから受け取ったレスポンスのうち、テーブルDTOの場合、必要な列だけに絞って、レスポンスとして、設定する。
→ 記載方法としてはパラメータの物理名を行単位で箇条書きで書いていくのみ。
2.4 備考
→BFF内での処理の概要を書く。
→ビジネスルールの処理詳細に近いイメージ。
→項番を振っていき、処理の概要を細分化していく。
→あくまでもDB取得などはしない変換処理のみにすること。
例）
① 当BFFで受け取った内容を元に、BE「顧客情報取得」を呼び出す。
② ①で取得したレスポンスの内、顧客テーブルDTOのうち、顧客IDと顧客名を取得する。
③ ①で取得したレスポンスの内、年収テーブルDTOのうち、顧客IDと年収を取得する。
④ ②の顧客IDと③の顧客IDを付き合わせて、合致した場合、
以下のレスポンスの内容を設定する。
顧客ID→合致した顧客ID
顧客名→合致した顧客IDに紐づく、顧客名
年収→合致した顧客IDに紐づく、年収
3. BE
BFFから呼ばれるAPIとなります。
APIの呼び出されるController、ビジネスロジックを実装するService、DBからの取得を行うRepositryごとに階層が分かれます。
（基本的なSpring Bootのアーキテクチャに基づいて、分けております。）
3.1 API名
→BEのAPI名となります。BFFのAPI名と重複するのは問題ないですが、BE一覧内でのAPI名は一意とします。
3.2 通信方法
→ 記載観点として、取得であれば、GET、更新系であれば、POST、PUTのいずれか（推奨はPOST)
3.3 パラメータ
→「3.2 通信方法」において、GETであれば、ここにパスパラメータまたはクエリパラメータで連携する値をパラメータとして記載する。
→ 記載観点として、取得時にキーとなる項目がメインとして渡されることが想定される。
→ 記載方法としてはパラメータの物理名を行単位で箇条書きで書いていく。
3.4 リクエスト
→「3.2 通信方法」において、POST(PUT)であれば、ここに、BEへのリクエストボディのパラメータを記載します。
→ 記載観点として、BFFで受け取ったパラメータのうち、必要な情報のみを渡す想定。
（BFFから複数のBEを別で呼び出す場合はBEごとに必要なパラメータに絞って設定）
3.3 レスポンス
→「3.2 通信方法」の内容に関わらず、記載すること。
→ 記載観点として、 Repositoryで取得したテーブルDTOを返す想定。
→ 複数のテーブルからの取得がある場合はテーブルDTOを行単位で箇条書きで書いていく。
3.4 Controller
BFFから呼ばれた際に最初に呼ばれる階層。
値の最初の受け取り口と最終的な返し口となる。
ここからServiceを呼ぶ際にModelの形をhelperクラスを使用して変換することもある。
3.4.1 名称
→ Controllerの名称となります。BEのAPI名と同一の名称でも良い。
3.4.2 パラメータ
→ Controllerのメソッドのパラメータを記載するため、基本的にはBEの「3.3 パラメータ」と同一となる。
3.4.3 戻り値
→ Controllerのメソッドの戻り値を記載するため、基本的にはBEの「3.3 レスポンス」と同一となる。
3.5 Service
Controllerから呼ばれる階層。
パラメータの値の取り出しや変換、DBからの取得結果の判定やビジネスロジックは全てここで処理を記載する。
ここでRepositoryごとに値を分けて設定して呼び出しを行ったりもします。
3.5.1 名称
→ Serviceの名称となります。BEのAPI名と同一の名称でも良い。
3.5.2 パラメータ
→ Serviceのメソッドのパラメータを記載するため、基本的にはBEの「3.3 パラメータ」と同一となる。
3.4.3 戻り値
→ 呼ばれるのメソッドの戻り値を記載するため、基本的にはBEの「3.3 レスポンス」と近いものが設定されるが、Serviceで特有の処理をして値を算出した場合は、追加して、戻り値にすることが想定される。（配列型でテーブルDTOを返すこともできます）
3.6 Repository
１テーブル単位や取得する結合テーブル単位で分けて宣言します。
１テーブルあたり、１Repositoryで分けて宣言し、ServiceからRepositoryをそれぞれキーを変えて呼び出したりします。
しかし、結合などで同時に取れる場合は１メソッドにまとめても良い。
3.6.1 名称
→ テーブルの名称と同一にします。
3.6.2 パラメータ
→ 対象のテーブルのテーブル検索やテーブル更新に必要なキー値のみを渡します。
→ Service側で対象Repositoryに必要な値を取り出して精査する必要があります。
3.6.3 戻り値
→ 取得したテーブルのDTOを返します。（配列型でテーブルDTOを返すこともできます）
3.6.4 対象テーブル
→ 対象のテーブル名を記載します。
3.6.5 備考
→ 対象テーブルの取得に必要な検索条件、更新時に必要な更新条件、結合時に必要な結合条件などSQLを書かないまでも、必要な操作方法をきちんと明記します。
→ ここの内容はmybatisなどに記載する条件となるため、ここを鮮明にしないと、そもそも正しいDB操作を行うことができません。
→ 基本的には検索時や更新時などもテーブルのDTOをそのまま返すために、取得列の情報などは記載不要。
例）
※検索結果が0件の場合、顧客テーブルDTOをNULLで返す。
【検索条件】
WHERE 対象年月 = '【パラメータ.対象年月】'
AND 対象週 = ''【パラメータ.対象週】'
AND 論理削除フラグ = '0'
３. 実例
以下、２を踏まえのフォーマットとなります。
次回、④ OpenAPIを使用してのSwagger EditorのIF設計書へ続く。。