From fcb9e4257f5072d2547e46b48da6f4df193d5a8e Mon Sep 17 00:00:00 2001 From: Yosuke Ota Date: Tue, 24 Dec 2024 08:59:18 +0900 Subject: [PATCH] =?UTF-8?q?fix:=20=E9=96=93=E9=81=95=E3=81=A3=E3=81=9FHead?= =?UTF-8?q?ing=E6=A7=8B=E6=88=90=E3=81=AE=E4=BF=AE=E6=AD=A3&Heading?= =?UTF-8?q?=E3=81=AE=E4=BB=95=E7=B5=84=E3=81=BF=E3=82=92=E8=AA=BF=E6=95=B4?= =?UTF-8?q?=20(#199)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vitepress/config.mjs | 7 ++ .../lib/markdown-it-plugin-header-shift.mjs | 22 +++++ ...75\345\220\215\350\246\217\347\264\204.md" | 80 +++++++++---------- documents/forGitBranch/index.md | 2 +- documents/forJava/index.md | 14 ++-- .../OpenAPI_Specification_2.0.md | 68 ++++++++-------- documents/forOpenAPISpecification/index.md | 8 +- documents/forSQL/index.md | 8 +- index.md | 2 +- 9 files changed, 120 insertions(+), 91 deletions(-) diff --git a/.vitepress/config.mjs b/.vitepress/config.mjs index 6e878af8..cd9716ed 100644 --- a/.vitepress/config.mjs +++ b/.vitepress/config.mjs @@ -66,6 +66,13 @@ const links = { link: "/documents/forGitBranch/git_branch_standards.html", }, ], + "/documents/forMarkdown/": [ + { text: "Introduction", link: "/documents/forMarkdown/" }, + { + text: "Markdown設計ドキュメント規約", + link: "/documents/forMarkdown/markdown_design_document.html", + }, + ], "/documents/forSlack/": [ { text: "Introduction", link: "/documents/forSlack/" }, { diff --git a/.vitepress/lib/markdown-it-plugin-header-shift.mjs b/.vitepress/lib/markdown-it-plugin-header-shift.mjs index 863dc432..595caeb0 100644 --- a/.vitepress/lib/markdown-it-plugin-header-shift.mjs +++ b/.vitepress/lib/markdown-it-plugin-header-shift.mjs @@ -1,10 +1,32 @@ +// @ts-check +/** + * @typedef {import('markdown-it/lib/rules_core/state_core.mjs').default} StateCore + * @typedef {import('markdown-it').default} MarkdownIt + */ /** * headerタグを1つづつずらします。 * Pandocでも利用できるMarkdownファイルにしたいので、`# header`を一つしかつくれないvitepress制約がうまく共存できないため、 * vitepressではhタグの番号をずらし、無理やり共存できるようにします。 + * @param {MarkdownIt} md */ export default function headerSections(md) { + /** + * + * @param {InstanceType} state + * @returns + */ function shiftHeaders(state) { + if ( + !state.tokens.some( + (token) => + token.type === "html_inline" && + token.content.startsWith("がない場合は何もしない + return; + } + state.tokens.forEach((t, i) => { if (t.type.includes("heading")) { t.tag = t.tag.replace(/^h(\d)$/, (_h, n) => `h${n - 0 + 1}`); diff --git "a/documents/forAWSResource/AWS\343\202\244\343\203\263\343\203\225\343\203\251\343\203\252\343\202\275\343\203\274\343\202\271\345\221\275\345\220\215\350\246\217\347\264\204.md" "b/documents/forAWSResource/AWS\343\202\244\343\203\263\343\203\225\343\203\251\343\203\252\343\202\275\343\203\274\343\202\271\345\221\275\345\220\215\350\246\217\347\264\204.md" index 030d1930..5fdc452c 100644 --- "a/documents/forAWSResource/AWS\343\202\244\343\203\263\343\203\225\343\203\251\343\203\252\343\202\275\343\203\274\343\202\271\345\221\275\345\220\215\350\246\217\347\264\204.md" +++ "b/documents/forAWSResource/AWS\343\202\244\343\203\263\343\203\225\343\203\251\343\203\252\343\202\275\343\203\274\343\202\271\345\221\275\345\220\215\350\246\217\347\264\204.md" @@ -22,7 +22,7 @@ head: ::: -## 前提条件 +# 前提条件 - 開発チームが 3 ～ 30 名程度で構築する規模での利用を想定している - 本規約をそのままプロジェクトに導入することを推奨する @@ -32,7 +32,7 @@ head: - 一部のリージョンでのみ利用可能な機能は想定していない - 例えば、[AWS Local Zones](https://aws.amazon.com/jp/about-aws/global-infrastructure/localzones/) は考慮しない -## 名前の構成要素 +# 名前の構成要素 各リソースの名前に用いる要素を次の一覧に示す。 @@ -50,7 +50,7 @@ head: | Organization | `{company}` | 会社名 | 会社の特定に利用。複数の会社による構築や、運用に複数社関わる場合などに必要となる | | | `{project}` | プロジェクト | プロジェクト制でプロダクトを開発する際のプロジェクト名または、プロジェクトコード | -### 環境 (`{env}`) +## 環境 (`{env}`) ソフトウェア開発では複数の環境を用意し、dev, stg, prod などの名前をつけて互いに完全に分離・区別する運用を行うことが多い。そういった環境分離のために AWS インフラは次のいずれか、もしくは組み合わせで設計される。 @@ -66,7 +66,7 @@ head: - チームメンバーなどの問い合わせやトラブルシュートの際に、リソース名のみでどの環境にあるか素早く判断できるようにする - メンバーの役割によっては AWS アカウント構成を完全には理解できていない可能性がある -#### 環境識別子 +### 環境識別子 主要な環境名と識別子 (Identifier) は以下である。AWS リソースの命名には識別子を用いる。 @@ -92,7 +92,7 @@ prod についてはよく用いる dev, stg と見間違えを防ぐため 4 - 識別子に採用した単語は一般的に用いられている略称である - その他の環境についても、環境識別子の数は通常そこまで多くならないず、またよく用いられるため、利用者にとっての認識負荷は少なく覚えるコストも低い -#### 同一目的の複数環境 +### 同一目的の複数環境 同一目的の環境が複数必要な場合は、識別子の末尾に連番をつける。 @@ -101,7 +101,7 @@ prod についてはよく用いる dev, stg と見間違えを防ぐため 4 - dev1, dev2, dev3 - stg1, stg2 -### 役割 (`{role}`) +## 役割 (`{role}`) アプリケーションを構成する要素には役割がある。それを AWS リソース名に含めることで、開発者の理解を助け、操作ミスを低減する。 @@ -120,13 +120,13 @@ prod についてはよく用いる dev, stg と見間違えを防ぐため 4 名前を一般化せず、プロダクト名をそのまま利用しても問題ない。例えば、Web アプリサーバに `tomcat`、CI/CD サーバに `jenkins` といった名称を使っても良い。 -### 用途 (`{usage}`) +## 用途 (`{usage}`) 利用目的やリソースの動作 (action) を示す。user_master, fileupload といった形式や、認証(auth)や BFF（Backend For Frontend）など。 役割 (`{role}`) と合わせてリソースが一意に特定できる名称を設定する。 -### リージョン (`{region}`) +## リージョン (`{region}`) マルチリージョン構成を取り、リージョンを意識する必要のある場合に利用する。[リージョンコード](https://docs.aws.amazon.com/ja_jp/general/latest/gr/rande.html) そのものではなく略称を識別子として用いる。 @@ -143,7 +143,7 @@ prod についてはよく用いる dev, stg と見間違えを防ぐため 4 シングルリージョン構成または、リージョン間のリソースの関係が疎である場合はリージョン識別子を付与しない。 -### アベイラビリティゾーン (`{az}`) +## アベイラビリティゾーン (`{az}`) AZ 名にはリージョンコードを含めず、末尾のアルファベットだけとする。 @@ -155,7 +155,7 @@ AZ 名にはリージョンコードを含めず、末尾のアルファベッ - 利用可能な文字: `[a-d]{1}` -### アクセス修飾子 (`{access}`) +## アクセス修飾子 (`{access}`) VPC のサブネットは、パブリックサブネットの場合インターネットに直接アクセスできる。パブリックサブネットを区別したい場合はリソース名にアクセス修飾子を付与する。 @@ -164,9 +164,9 @@ VPC のサブネットは、パブリックサブネットの場合インター | パブリックサブネット | public | | プライベートサブネット | private | -## 全体ポリシー +# 全体ポリシー -### 命名規約 +## 命名規約 次のように各要素を使ってケバブケース (`kebab-case`) で命名する。パスカルケース (`PascalCase`) やスネークケース (`snake_case`) は利用しない。なお、サービス名自体にパスカルケースを用いることは許容する @@ -180,7 +180,7 @@ VPC のサブネットは、パブリックサブネットの場合インター - ほぼ全ての AWS サービスではリソース名にハイフンを許容する。一方で、アンダースコアを許容しない WebACL のようなサービスがある - 環境名、サービス名などの単位で区切りを明確にできる -### 利用可能な文字 +## 利用可能な文字 利用する文字は、半角英数字とハイフンに限定する。また、 **小文字を推奨** する。 @@ -188,7 +188,7 @@ VPC のサブネットは、パブリックサブネットの場合インター また、先頭文字には半角英字を用い (ハイフン、数値を先頭にしない)、ハイフンは 2 文字以上連続させないこととする。 -### AWS サービス名を含めない +## AWS サービス名を含めない リソース名に AWS サービス名を含めない。 @@ -216,7 +216,7 @@ stg-fuga-web-fileupload-bucket ただし、VPC エンドポイントやセキュリティグループのように、どの AWS サービスの何で利用されているかを示す場合には利用することがある。 -### プロジェクト名を含めない +## プロジェクト名を含めない プロジェクト制を取っている場合、その開発チームの持ち物であることを示すためプロジェクト名をリソース名に含めたくなるが非推奨である。 @@ -227,7 +227,7 @@ stg-fuga-web-fileupload-bucket プロジェクト名の替わりにプロダクト名を含めることとする。 -### マルチクラウドを考慮し、aws 識別子を追加するかどうか +## マルチクラウドを考慮し、aws 識別子を追加するかどうか AWS だけではなく、Azure や GCP などを組み合わせたマルチクラウド運用を行っている、あるいは行う予定がある場合を考慮し、リソース名に `aws` といったプレフィックス/サフィックスを付与する考えもある。 @@ -238,13 +238,13 @@ AWS だけではなく、Azure や GCP などを組み合わせたマルチク - 同一 product を異なるクラウドサービスで運用することは稀 - 一部のサービス (例えば DWH のみ Google BigQuery を利用するようなケース) だけの使用であれば、`{usage}` で区別すれば十分である -## サービス別の命名規約 +# サービス別の命名規約 サービスによって異なる命名規約と例を記載する。 以下ではプロダクト名を `fuga` とした場合の例をあげる。 -### VPC +## VPC VPC に関わるリソースの命名について記載する。 @@ -259,7 +259,7 @@ VPC に関わるリソースの命名について記載する。 | Endpoint | `{env}-{product}-{aws_service}` | stg-fuga-s3 | 様々なサービスが利用するため AWS サービス名を含めている | | Security Group | `{env}-{product}-{aws_service}-{usage}` | stg-fuga-ec2-bastion | 様々なサービスが利用するため AWS サービス名を含めている | -### API Gateway +## API Gateway
AWS上の命名制約 @@ -281,7 +281,7 @@ stg-fuga-web-fileupload-public - API Gateway には複数の機能種別 (REST, HTTP) が存在するが、命名には含めない - private/public を名前に含めることで、public は認証が入っているかなどをチェックできる -### EC2 +## EC2 インスタンス名の制限=タグの制限のため、名前は [Amazon EC2 リソースのタグ付け](https://docs.aws.amazon.com/ja_jp/AWSEC2/latest/UserGuide/Using_Tags.html) に従う必要がある。 @@ -295,7 +295,7 @@ stg-fuga-web オートスケーリング、オートヒーリング構成をする場合にどこの AZ に配置するかを意識させないため、リソース名に AZ は基本的に含めない。そのような構成をしないという方針は、アンチパターンのため構成を見直すべきと考える。 -### LB +## LB
AWS上の命名制約 @@ -328,7 +328,7 @@ stg-fuga-web-api-public stg-fuga-web-public-blue ``` -### ECS +## ECS
AWS上の命名制約 @@ -365,9 +365,9 @@ stg-fuga-web-frontend stg-fuga-batch-import-address ``` -### Lambda +## Lambda -#### Lambda Function +### Lambda Function
AWS上の命名制約 @@ -399,7 +399,7 @@ stg-fuga-report-successrate {env}-{product}-{role}-{usage}-gather ``` -#### Lambda Layer +### Lambda Layer
AWS上の命名制約 @@ -419,7 +419,7 @@ stg-fuga-python310-auth stg-fuga-nodejs18-frontend ``` -### RDS/Aurora +## RDS/Aurora
AWS上の命名制約 @@ -472,7 +472,7 @@ DB サブネット - [VPC](#vpc) のサブネットを参照 -### DynamoDB +## DynamoDB
AWS上の命名制約 @@ -497,7 +497,7 @@ stg-fuga-user-accesslog なお、インデックス名は `idx-1`, `idx-2` のような連番での管理を推奨する。RDB とは異なりアカウント単位での一意性は不要なため、テーブル名は含めなくても良いため、 `idx_{テーブル名}_{連番}` としなくても良い。DynamoDB は 最大で 20 のグローバルセカンダリインデックス を持つことができるが、インデックスの数は最小限に抑えることが鉄則であるため、0 埋めしない。ただし、要件上どうしても多用が避けられないことが判明している場合は `idx-01`, `idx-02` と 0 埋めする。 -### S3 Bucket +## S3 Bucket
AWS上の命名制約 @@ -533,7 +533,7 @@ stg-fuga-alb-logs stg-fuga-userinfo-fis-if ``` -### Kinesis Data Streams +## Kinesis Data Streams
AWS上の命名制約 @@ -569,7 +569,7 @@ stg-fuga-import-iotsensor-toggle stg-fuga-call-job-arrival-check ``` -### SQS +## SQS
AWS上の命名制約 @@ -598,7 +598,7 @@ stg-future-fuga-processresult stg-future-fuga-processresult.fifo ``` -### Event Bridge Rule +## Event Bridge Rule
AWS上の命名制約 @@ -620,11 +620,11 @@ stg-fuga-polling-schedule-lambda ※スケジュールタイプのルールの場合は `{source}` に `schedule` と記載する。 -### IAM +## IAM IAM に関わるリソースの命名について記載する。IAM グループ、IAM ユーザー、IAM ロール、IAM ポリシーの 4 点について述べる。 -#### IAM ユーザー +### IAM ユーザー IAM ユーザーについては、誰 (人またはシステム) が利用するのかを識別することを目的とする。同じユーザーを複数の人やシステムで使いまわすと、誰が操作したのかといった証跡を追えなくなってしまうため、個別に発行することを推奨する。 また、役割や権限といった情報は名前に含めない。そのような名前はユーザーに紐づけるロールが増えた際などに名前と役割や権限の実態が乖離してしまうためである。 @@ -665,7 +665,7 @@ AWS サービスに権限付与する場合は IAM ロールで付与するこ - ある AWS アカウントに対して、Switch Role などで別の環境にアクセスする際に混乱が生じる - ブラウザのパスワード管理などのために ID 名を分けたいという考えもあるかもしれないが、パスワード管理アプリなどの利用を推奨する -#### IAM グループ +### IAM グループ IAM グループに IAM ユーザーを追加することで複数ユーザーの権限を一括管理できる。IAM ユーザーは複数の IAM グループに追加可能だが、所属可能なグループ数は最大で 10 という制約があるため注意が必要である。 @@ -700,7 +700,7 @@ bastion-access 例外的に特定のユーザーにのみ権限を付与する、会社を超えて共通のグループを付与するといったユースケースも考えられる。 -#### IAM ロール +### IAM ロール IAM ロールは、AWS サービスに権限を付与する目的で利用する。IAM ロールに複数の IAM ポリシーをアタッチできるため、IAM ロールの命名では細かい権限を表現することは避け、IAM ロールを誰が使うのかを明確にすることを主目的とする。 @@ -715,7 +715,7 @@ stg-fuga-lambda-api ※場合によっては `{usage}` 部に詳細情報を追加しても良い -#### IAM ポリシー +### IAM ポリシー IAM ポリシーの命名に入る前に、ポリシーの設計方針について記載する。 ここでは、ポリシー設計方針の代表例として、以下の 2 パターンについて説明する。 @@ -789,7 +789,7 @@ IAM グループ用のポリシーを作成する例では、company を含め 予め用意されているポリシーの名前は `PascalCase` 形式であるが (例: AmazonS3FullAccess)、ユーザーが作成したことを明確にするため `snake_case` で命名する。 -## タグの命名 +# タグの命名
AWS上の命名制約 @@ -817,7 +817,7 @@ IAM グループ用のポリシーを作成する例では、company を含め より詳しいタグ付けのベストプラクティスも存在するが、本紙の範囲を超えるため紹介のみに留める。 [https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html) -### タグキー +## タグキー - 使用する文字は英数字に限定する。基本的には **パスカルケース (PascalCase)** 形式を推奨する - リソース作成時に自動生成される `Name` タグと平仄を合わせるため @@ -842,7 +842,7 @@ IAM グループ用のポリシーを作成する例では、company を含め | ツールで利用 | StartAt | | 起動時刻。自動化ツールなどで必要があれば設定 | | | EndAt | | 停止時刻 | -### タグ値 +## タグ値 - 各タグキーごとに原則、タグ値の元となる命名規約に従う - 元となる命名規約がない場合、以下を推奨する @@ -850,7 +850,7 @@ IAM グループ用のポリシーを作成する例では、company を含め - 頭文字のみの略語の場合は大文字のみ - 値の取りうるパターンが決まっている場合には、タグポリシーで値を設定する -### タグポリシー +## タグポリシー AWS Organizations を利用している場合、タグの標準化を促進するタグポリシーの設定が可能となる。 タグポリシーにより実現できることは以下。 diff --git a/documents/forGitBranch/index.md b/documents/forGitBranch/index.md index 26e668e1..3405cb67 100644 --- a/documents/forGitBranch/index.md +++ b/documents/forGitBranch/index.md @@ -27,6 +27,6 @@ hero: [pandoc]: https://pandoc.org/ -# Articles +## Articles - 2024.12.14 [Gitブランチフロー規約の紹介](https://future-architect.github.io/articles/20241214a/) diff --git a/documents/forJava/index.md b/documents/forJava/index.md index 30b9c981..4633c875 100644 --- a/documents/forJava/index.md +++ b/documents/forJava/index.md @@ -16,16 +16,16 @@ hero: 一般的に行われているコーディング規約から、Stream API やラムダ式、最新の Java17 で追加された構文にも対応しています。 -# For Java17 +# Java Coding Standards -Java17 向けのコーディング規約は[こちら](./Javaコーディング規約.md)です。 +- [Javaコーディング規約](./Javaコーディング規約.md) ... Java17+ 向けのコーディング規約 -# For Old Versions +## Old Versions -- Java11 向けのコーディング規約は[こちら](./Javaコーディング規約_for_11.md)です。 -- Java8 向けのコーディング規約は[こちら](./Javaコーディング規約_for_8.md)です。 +- [Javaコーディング規約 for Java11](./Javaコーディング規約_for_11.md) ... Java11 向けのコーディング規約 +- [Javaコーディング規約 for Java8](./Javaコーディング規約_for_8.md) ... Java8 向けのコーディング規約 -# Resources +## Resources 次のリンクから単一ファイルで作成されたコーディング規約を取得できます。\ (これらのファイルは[Pandoc]を利用して作成しています。) @@ -41,7 +41,7 @@ Java17 向けのコーディング規約は[こちら](./Javaコーディング [pandoc]: https://pandoc.org/ -# Articles +## Articles - 2021.10.07 [Java17対応版！Javaコーディング規約の紹介](https://future-architect.github.io/articles/20211007a/) - 2016.09.02 [システム屋さんがうれしいJava8対応のコーディング規約を公開します！！](https://future-architect.github.io/articles/20160902/) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md index 3297b17d..87fde9c4 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md @@ -30,11 +30,11 @@ Web API 自体の設計については範囲外としますが、[API 設計標 ::: -## ファイルフォーマット +# ファイルフォーマット [ファイルフォーマット規約](file_standards.md)に準じる。 -## 要素規約 +# 要素規約 Swagger の基本構造は以下の、swagger・info・host・basePath・schemes・paths・definitions から構成される。 @@ -124,11 +124,11 @@ definitions: example: "2023-04-01T11:30:45.000Z" ``` -## swagger +# swagger - `2.0` 固定とする -## info +# info info オブジェクトには Web API に関するメタデータを記載する。 `title`, `description`, `version` を必須項目とする。 @@ -142,22 +142,22 @@ info オブジェクトには Web API に関するメタデータを記載する | contact | | 連絡先情報 | | license | | ライセンス情報 | -### title +## title WebAPI の総称を記載する。システム名やサービス名 + API のような命名とすることを推奨する。 例. `X System API` -### desctiption +## desctiption Web API が提供する機能の概要・想定する利用者やユースケース・制約などを記載する。 -### version +## version この API 仕様のドキュメントのバージョンを記載する。アプリケーションのバージョン（git tag やリリースで管理するようなバージョン）とは別である。 本規約の推奨は `major.minor` 形式である。 `0.1 `固定で開発を進め、サービスのリリース時に `1.0` とし、その後の項目やオプション、パスの追加ごとに `1.1` などインクリメントしていく。もし他チームへのドキュメントの頻繁な共有が必要だれば、`1.0` のかわりに `2023.03.26` といった形式も許容する。 -## host +# host OpenAPI 3 系と異なり、 **Swagger では複数のホストを指定できない**。そのため host には開発環境（local, develop, staging, production というステージ区別であれば、develop）で用いる IP、ポート番号を指定する。他チームに提供するサンドボックス環境を用意する場合は、そのエンドポイントを指定しても良い。localhost などのローカル開発への向き先変更は、ツール側で対応している事が多く上書き可能なため記載しない。API 定義書は予期せぬタイミングで他チームに展開する必要がしばしばあり、お試しで触っても良い環境があることを示すことで情報量を増やし、円滑なコミュニケーションを促進することを狙いとする。 @@ -173,7 +173,7 @@ host: localhost:8001 host: prod.api.example.com:80 ``` -## basePath +# basePath 作成する Swagger 定義の URL パスの全てで、共通するプレフィックスを持つ場合に指定する。Swagger の仕様上、先頭には `/` が必須であるため、以下のように定義する。 @@ -186,7 +186,7 @@ basePAth: /api/v2 basePath: v2 ``` -## schemes +# schemes 最終的に利用するスキーマのみを記載する。通常、HTTP 通信での Web API 提供は行わないと考えられるため、 `https` 固定で設定する。ローカル開発では `http` を指定することも多いが、ツールで生成されたコードのオプションで通常書き換えが可能なため、`http` の併記は許可しない。ただし、サーバサイドのマイクロサービス同士の通信で、VPC（プライベートセグメント）内であり、SSL 通信を本当に利用しない場合は `http` と記載する。 @@ -203,7 +203,7 @@ schemes: もし、WebSocket スキームを提供するサービスの定義である場合は、`wss` を（追加で）指定する。定義上は `https` 側との共存ができないため、ファイル定義を分けるようにする。 -## security, securityDefinitions +# security, securityDefinitions Swagger では、次の認証タイプを記載できる（[詳細](https://swagger.io/docs/specification/2-0/authentication/)）。 @@ -231,7 +231,7 @@ paths: - OAuth2: [] ``` -## produces +# produces Web API が応答する際の MIME タイプを指定します。未指定の場合に、コード生成などツール側で予期しない動作をすることがあるため、固定で指定する。新規構築の Web API であれば `application/xml` は不要と通常は考えられるので、`application/json` を記載する。また、[RFC 7807 Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc7807) では Content-Type に `application/problem+json` を設定するとあるが、一部のコード生成ツールにおいて、 `application/problem` と `application/problem+json` の使い分けが難しいため、併記を必須としない。OpenAPI Specification の 3 系ではステータスコードごとに Content-Type を指定できるため、3 系への移行も検討する。 @@ -264,7 +264,7 @@ paths: type: file ``` -## consumes +# consumes Web API が要求を受け入れる際の MIME タイプを指定する。未指定の場合に、コード生成などツール側で予期しない動作をすることがあるため、固定で指定する。新規構築の Web API であれば `application/xml` は不要と通常は考えらえるので、`application/json` だけ記載する。 @@ -276,7 +276,7 @@ consumes: - application/json ``` -## tags +# tags タグを用いて、API 操作をグループ化することができる。ドキュメントやツールにとって非常に重要であるため、 **必須** で指定する。 @@ -305,7 +305,7 @@ tags: - name: UserAccount ``` -## paths +# paths `paths` 配下に個々の API エンドポイントを記載する。 @@ -320,7 +320,7 @@ Paths # API定義全体 └ Response # ステータスコードに応じたレスポンス ``` -### Paths > Path +## Paths > Path 記載順は以下のルールである。 @@ -356,7 +356,7 @@ paths: ... ``` -### Paths > Path > Operation +## Paths > Path > Operation URL に紐づく HTTP メソッドで、1 つの操作を定義します。 @@ -389,7 +389,7 @@ URL に紐づく HTTP メソッドで、1 つの操作を定義します。 responses: ... ``` -### Paths > Path > Parameter +## Paths > Path > Parameter リクエストの定義を記載する。 @@ -476,7 +476,7 @@ URL に紐づく HTTP メソッドで、1 つの操作を定義します。 ... ``` -### Paths > Path > Responses +## Paths > Path > Responses レスポンスの定義を記載する。 @@ -543,7 +543,7 @@ URL に紐づく HTTP メソッドで、1 つの操作を定義します。 $ref: "#/definitions/Error" ``` -## definitions +# definitions - モデル名は、PascalCase で記載する - 種別が配列の場合、ネストして定義するのではなく、 `$ref` を活用する @@ -683,17 +683,17 @@ definitions: example: user name is too long ``` -## バリデーションについて +# バリデーションについて OpenAPI 定義を記載するにあたり、バリデーションをどこまで厳密に定義すべきかという議論はよく行いがちである。 リクエストパラメータの各項目に対して、必須・型・桁・区分値・日付・正規表現のチェックが行える。レスポンスで用いるモデルについても同様に設定でき、`enum`, `pattern` 以外は API の利用者（クライアント）側の DB 設計などに必要な型桁情報を渡すのに有用であるため、できる限り詳しく指定する。 -### 必須 +## 必須 必須パラメータのみ `required: true` を定義する -### デフォルト値 +## デフォルト値 パラメータにデフォルト値がある場合は`default` を定義する。 @@ -710,7 +710,7 @@ description: 検索結果の項目数上限（1~100が指定可能） 【注意】API 公開後に、default 値を変更してはならない（API の互換性が崩れるため）。もし変更する場合は、API のバージョンを上げること。 -### 型・フォーマット +## 型・フォーマット 型（`type`）は `string(文字列)`, `number（数値）`, `integer（整数値）`, `boolean（真偽値）` `array（配列）`, `file（ファイル）` のうちどれか指定する. @@ -732,7 +732,7 @@ description: 検索結果の項目数上限（1~100が指定可能） - `password`: Swagger UI で入力が隠される - その他、 `email`, `uuid` など Open API 仕様に存在しない任意のフォーマットを独自のドキュメント生成などのために記載しても良い -### 桁 +## 桁 データ型によって、利用できる桁を指定する項目が異なる。可能な限り設定する。 @@ -751,7 +751,7 @@ description: 検索結果の項目数上限（1~100が指定可能） 【注意】API 公開後に、レスポンスの `maxLength` を以前より大きい値に変更してはならない。レスポンスの `maxLength` など API 利用者側システムの DB の ERD 定義のインプットになる事が多いため。もし行う場合は API のバージョンを上げることや、連携先に桁数変更の旨を調整するなどの考慮を行う。 -### 区分値 +## 区分値 区分値の場合は `enum` 属性を利用し、`description`には区分値の論理名を記載する。 @@ -767,7 +767,7 @@ description: | 9: 適用不能 ``` -### 固定値 +## 固定値 **固定値** の場合も enum を 1 つだけ指定して表現する。この場合もレスポンスで利用する場合は指定しない @@ -778,7 +778,7 @@ enum: ["json"] description: ファイルレイアウト ``` -### その他（正規表現） +## その他（正規表現） 正規表現で表現できる文字列は`pattern`を利用して定義する。桁や区分値で代替できる場合は、`pattern` を用いない @@ -792,7 +792,7 @@ remind_time: pattern: "^(2[0-3]|[01][0-9]):([0-5][0-9])$" ``` -## ファイルアップロード +# ファイルアップロード Web API におけるファイルアップロードのよく利用される実装手段は、大きく分けて以下の 3 手法に分類できます @@ -833,7 +833,7 @@ A->>B: ③ファイルアップロード完了(受付ID、キー、属性) 上記どちらのケースも OpenAPI 定義としてはシンプルであるため、記述例は割愛する。 -## ファイルダウンロード +# ファイルダウンロード ファイルアップロードと同様、オブジェクトストレージの Signed URL 経由を経由してのダウンロードさせる手法を推奨する。Web API としてはオブジェクトストレージにダウンロード用のファイルを書き込み、クライアントが取得するための Signed URL をレスポンスの JSON 項目に渡す方式である。 @@ -841,7 +841,7 @@ A->>B: ③ファイルアップロード完了(受付ID、キー、属性) どちらのケースも OpenAPI 定義としてはシンプルであるため、記述例は割愛する。 -## CORS +# CORS CORS（Cross-Origin Resource Sharing）のために、options メソッドの追記は **原則不要** とする。 @@ -858,7 +858,7 @@ CORS（Cross-Origin Resource Sharing）のために、options メソッドの追 [^1]: https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/enable-cors-for-resource-using-swagger-importer-tool.html -## OpenTelemetry Traceparent HTTP Header +# OpenTelemetry Traceparent HTTP Header OpenOpenTelemetry で用いるられる[traceparent](https://www.w3.org/TR/trace-context/) のリクエストヘッダーは OpenAPI で **原則不要** とする。 @@ -867,7 +867,7 @@ OpenOpenTelemetry で用いるられる[traceparent](https://www.w3.org/TR/trace - OpenTelemetry が定めるヘッダー類は、API 横断的に設定されるべきものであり、ミドルウェアやフレームワーク側などでの一律の制御を推奨するため - 記載することにより、OpenOpenTelemetry に対応していることを明記し開発者に周知できるメリットより、各アプリ開発者が生成されたコードで悩んだり、誤解されることを回避したいため -## API のバージョン管理 +# API のバージョン管理 Swagger 定義で以下の変更を行う場合は、利用するコード生成の動作によってはクライアントにとって互換性を失う破壊的変更であることがあるため、変更は調整の上で行うか、バージョンを上げることを考える。 @@ -883,7 +883,7 @@ Swagger 定義で以下の変更を行う場合は、利用するコード生成 - 桁数を大きくする - デフォルト値を後から変更する -## ファイル単位 +# ファイル単位 TODO v3 の作成タイミングと合わせて追記する diff --git a/documents/forOpenAPISpecification/index.md b/documents/forOpenAPISpecification/index.md index 29c8857a..126835f6 100644 --- a/documents/forOpenAPISpecification/index.md +++ b/documents/forOpenAPISpecification/index.md @@ -16,7 +16,7 @@ hero: OpenAPI Specification（OAS）の規約を、設計・開発・テスト・可読性・保守性・ツールによるコード生成や静的解析の観点からまとめています。 -# 対応するバージョンについて +## 対応するバージョンについて OpenAPI Specification（OAS）の規約を設計、開発、テスト、可読性、保守性、ツールによるコード生成や静的解析の観点からまとめています。 @@ -42,14 +42,14 @@ OAS は次のように複数のバージョンが存在します。 [https://openapi.tools/](https://openapi.tools/) -# OpenAPI Specification Standards +## OpenAPI Specification Standards | Version | コーディング規約 | | ------- | ------------------------------------------------------------ | | 3.0.3 | [OAS 3.0.3 規約](./OpenAPI_Specification_3.0.3.md) | | 2.0 | [OAS 2.0（Swagger 2.0）規約](./OpenAPI_Specification_2.0.md) | -# Resources +## Resources 次のリンクから単一ファイルで作成されたコーディング規約を取得できます。 (これらのファイルは[Pandoc]を利用して作成しています。) @@ -60,7 +60,7 @@ OAS は次のように複数のバージョンが存在します。 [pandoc]: https://pandoc.org/ -# Articles +## Articles - 2024.07.02 [OpenAPI Specification v3.0.3のコーディング規約を公開しました](https://future-architect.github.io/articles/20240702a/) - 2023.07.25 [フューチャーのSwagger（OpenAPI 2.0）規約の紹介](https://future-architect.github.io/articles/20230725a/) diff --git a/documents/forSQL/index.md b/documents/forSQL/index.md index 797e4abc..e0f41070 100644 --- a/documents/forSQL/index.md +++ b/documents/forSQL/index.md @@ -20,10 +20,10 @@ hero: 次の SQL コーディング規約が利用できます。 -- PostgreSQL 向けのコーディング規約は[こちら](./SQLコーディング規約（PostgreSQL）.md)です。 -- Oracle 向けのコーディング規約は[こちら](./SQLコーディング規約（Oracle）.md)です。 +- [SQLコーディング規約（PostgreSQL）](./SQLコーディング規約（PostgreSQL）.md) ... PostgreSQL 向けのコーディング規約 +- [SQLコーディング規約（Oracle）](./SQLコーディング規約（Oracle）.md) ... Oracle 向けのコーディング規約 -# Resources +## Resources 次のリンクから単一ファイルで作成されたコーディング規約を取得できます。\ (これらのファイルは[Pandoc]を利用して作成しています。) @@ -39,6 +39,6 @@ hero: [pandoc]: https://pandoc.org/ -# Articles +## Articles - 2023.11.20 [新しいSQLフォーマッターであるuroboroSQL-fmtをリリースしました](https://future-architect.github.io/articles/20231120a/) diff --git a/index.md b/index.md index 20910b8d..fed7f0c2 100644 --- a/index.md +++ b/index.md @@ -33,6 +33,6 @@ features: [![GitHub last commit](https://img.shields.io/github/last-commit/future-architect/coding-standards.svg)](https://github.com/future-architect/coding-standards) [![GitHub stars](https://img.shields.io/github/stars/future-architect/coding-standards.svg?style=social&label=Stars&logo=github)](https://github.com/future-architect/coding-standards/stargazers) -# License +## License [![CC-By-4.0](https://licensebuttons.net/l/by/4.0/88x31.png)](https://creativecommons.org/licenses/by/4.0/deed.ja)