feat: スキーマを更新#10
Merged
Merged
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughOpenAPI定義と生成サーバーコードを同期。メール確認フロー（ Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (2)
openapi.yaml (2)
9-37: オペレーションにdescriptionフィールドがありません。Spectral の静的解析で指摘されている通り、
POST /verify-emailにdescriptionフィールドがありません。summaryは短い概要用で、descriptionはより詳細な説明（認証フロー、トークンの有効期限、リダイレクトパスの検証ルールなど）を記載するために使用されます。📝 descriptionの追加例
/verify-email: post: summary: isct メールアドレスを検証して JWT を発行 + description: | + isct ドメインのメールアドレスを検証し、認証用の JWT トークンを発行します。 + redirect パラメータで指定されたパスはバリデーション後にレスポンスに含まれます。 tags: - Auth🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openapi.yaml` around lines 9 - 37, The OpenAPI operation POST /verify-email (operationId: postVerifyEmail) is missing a descriptive description field; add a "description" for this operation that expands on the summary by explaining the verification flow, expected request/response behavior (e.g., token issuance and expiry), validation rules for the optional "redirect" query parameter, and any side effects or error conditions so Spectral validation passes and consumers understand usage.
504-507:StripeEventスキーマの型定義が緩すぎる可能性があります。
additionalProperties: trueのみでは、Webhook ペイロードの構造が不明確です。Stripe Event にはid、type、dataなどの必須フィールドがあります。Stripe 側での署名検証（
Stripe-Signatureヘッダー）が行われることを考慮すると、現状でも機能上は問題ありませんが、API ドキュメントとしての明示性やコード生成時の型安全性が低下します。💡 最小限の型定義を追加する例
StripeEvent: description: Generic Stripe event payload type: object + properties: + id: + type: string + description: Event ID + type: + type: string + description: Event type (e.g., invoice.paid) + data: + type: object + additionalProperties: true additionalProperties: true🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openapi.yaml` around lines 504 - 507, The StripeEvent schema is too permissive; update the StripeEvent object in openapi.yaml to explicitly declare its core fields (e.g., add properties id: string, type: string, created: integer or string(date-time), api_version: string (optional), and data: object with a nested object or object.value placeholder) and mark the required fields (at least id and type and data), while you may keep additionalProperties: true for forward compatibility; modify the StripeEvent definition (symbol: StripeEvent) to include these properties and required array to improve documentation and generated type safety.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@openapi.yaml`:
- Around line 9-37: The OpenAPI operation POST /verify-email (operationId:
postVerifyEmail) is missing a descriptive description field; add a "description"
for this operation that expands on the summary by explaining the verification
flow, expected request/response behavior (e.g., token issuance and expiry),
validation rules for the optional "redirect" query parameter, and any side
effects or error conditions so Spectral validation passes and consumers
understand usage.
- Around line 504-507: The StripeEvent schema is too permissive; update the
StripeEvent object in openapi.yaml to explicitly declare its core fields (e.g.,
add properties id: string, type: string, created: integer or string(date-time),
api_version: string (optional), and data: object with a nested object or
object.value placeholder) and mark the required fields (at least id and type and
data), while you may keep additionalProperties: true for forward compatibility;
modify the StripeEvent definition (symbol: StripeEvent) to include these
properties and required array to improve documentation and generated type
safety.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 641e2e2f-efff-436a-aa59-3039f83386c1
📒 Files selected for processing (2)
openapi.yamlserver/gen.go
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
openapi.yaml (1)
557-560: StripeEvent スキーマは汎用的な定義です。Stripe のイベントペイロードは多様なため、
additionalProperties: trueの汎用オブジェクトとして定義するのは実用的なアプローチです。ただし、typeやidなどの共通フィールドを明示的に定義することで、ドキュメントとしての価値が向上する可能性があります。💡 オプション: 共通フィールドの明示的定義
StripeEvent: description: Generic Stripe event payload type: object additionalProperties: true + properties: + id: + type: string + description: Stripe event ID + type: + type: string + description: Event type (e.g., invoice.paid)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openapi.yaml` around lines 557 - 560, The StripeEvent schema is currently a catch-all (additionalProperties: true); improve documentation and validation by explicitly declaring common Stripe event fields (e.g., properties: { id: { type: string }, type: { type: string }, api_version: { type: string }, created: { type: integer }, livemode: { type: boolean }, data: { type: object } }) and marking them as optional/required as appropriate while keeping additionalProperties: true; update the StripeEvent object definition to include these named properties so consumers see common fields yet retain flexibility.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openapi.yaml`:
- Line 358: 現在の pattern 値 "(?i)^[^@\s]+@isct\.ac\.jp$" は PCRE のインラインフラグ (?i)
を含んでおり OpenAPI (ECMA-262) で無効です。pattern
プロパティを編集し、インラインフラグを取り除いて代わりに大文字小文字を許容する文字クラスを使う（例:
^[^@\s]+@[Ii][Ss][Cc][Tt]\.ac\.jp$）か、あるいはスキーマレベルで JSON Schema の patternFlags
を使する方針に切り替えて修正してください（修正箇所: the pattern value currently set to
(?i)^[^@\s]+@isct\.ac\.jp$）。
- Around line 9-69: Add a detailed description field for each operation to
satisfy Spectral and provide clearer docs: for operationId postVerifyEmail (POST
/verify-email) add a description explaining that this endpoint accepts a
VerifyEmailRequest JSON body, sends a one-time verification email to the
provided address, optionally uses the redirect query param to build the
verification link, and returns 202 when the email dispatch is accepted; for
operationId getVerifyEmailConfirm (GET /verify-email/confirm) add a description
stating it validates the one-time token query param, completes login or account
verification and responds with a 303 redirect on success (or 400/401/500 as
documented); for operationId getCsrf (GET /csrf) add a description that the
endpoint issues a CSRF token cookie (no response body) and returns 204. Ensure
each description is placed under the operation's description field in the
OpenAPI spec.
- Around line 342-346: The OpenAPI spec defines a security scheme cookieAuth
(securitySchemes.cookieAuth, name: checkin_session) but it is not applied
anywhere; either remove the unused cookieAuth entry or apply it to relevant
operations/global security. To fix: if endpoints require the cookie session, add
a security requirement referencing cookieAuth to those operation objects or to
the global security root; otherwise delete the cookieAuth definition from
components.securitySchemes to avoid dead spec entries. Ensure you reference the
exact scheme name "cookieAuth" and cookie name "checkin_session" when making the
change.
---
Nitpick comments:
In `@openapi.yaml`:
- Around line 557-560: The StripeEvent schema is currently a catch-all
(additionalProperties: true); improve documentation and validation by explicitly
declaring common Stripe event fields (e.g., properties: { id: { type: string },
type: { type: string }, api_version: { type: string }, created: { type: integer
}, livemode: { type: boolean }, data: { type: object } }) and marking them as
optional/required as appropriate while keeping additionalProperties: true;
update the StripeEvent object definition to include these named properties so
consumers see common fields yet retain flexibility.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f2e38c82-a357-4f90-b372-b96ccea0fcee
📒 Files selected for processing (2)
openapi.yamlserver/gen.go
Comment on lines
+9
to
+69
| /verify-email: | ||
| post: | ||
| summary: isct メールアドレスの確認メールを送信 | ||
| tags: | ||
| - Auth | ||
| operationId: postVerifyEmail | ||
| parameters: | ||
| - name: redirect | ||
| in: query | ||
| description: 検証後に遷移する相対パス | ||
| schema: | ||
| type: string | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/VerifyEmailRequest' | ||
| responses: | ||
| '202': | ||
| description: Accepted | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/VerifyEmailStartResponse' | ||
| '400': | ||
| $ref: '#/components/responses/BadRequest' | ||
| '500': | ||
| $ref: '#/components/responses/InternalServerError' | ||
| /verify-email/confirm: | ||
| get: | ||
| summary: メール確認トークンを検証してログインを完了 | ||
| tags: | ||
| - Auth | ||
| operationId: getVerifyEmailConfirm | ||
| parameters: | ||
| - name: token | ||
| in: query | ||
| required: true | ||
| description: 確認メールに含まれるワンタイムトークン | ||
| schema: | ||
| type: string | ||
| minLength: 32 | ||
| responses: | ||
| '303': | ||
| description: See Other | ||
| '400': | ||
| $ref: '#/components/responses/BadRequest' | ||
| '401': | ||
| description: Unauthorized | ||
| '500': | ||
| $ref: '#/components/responses/InternalServerError' | ||
| /csrf: | ||
| get: | ||
| summary: CSRF トークン用 cookie を発行 | ||
| tags: | ||
| - Auth | ||
| operationId: getCsrf | ||
| responses: | ||
| '204': | ||
| description: No Content |
There was a problem hiding this comment.
description フィールドが不足しています。
Spectral のパイプライン警告によると、POST /verify-email、GET /verify-email/confirm、GET /csrf の各操作に description フィールドがありません。summary は短い概要ですが、description でより詳細な説明を提供することが推奨されています。
📝 description 追加の例
/verify-email:
post:
summary: isct メールアドレスの確認メールを送信
+ description: |
+ 指定されたメールアドレスに確認メールを送信します。
+ メールには確認用のワンタイムトークンが含まれます。
tags:
- Auth🧰 Tools
🪛 GitHub Actions: Run Spectral on Pull Requests
[warning] 10-10: Spectral (operation-description): Operation "description" must be present and non-empty string. paths./verify-email.post (https://meta.stoplight.io/docs/spectral/docs/reference/openapi-rules.md#operation-description)
[warning] 39-39: Spectral (operation-description): Operation "description" must be present and non-empty string. paths./verify-email/confirm.get (https://meta.stoplight.io/docs/spectral/docs/reference/openapi-rules.md#operation-description)
[warning] 62-62: Spectral (operation-description): Operation "description" must be present and non-empty string. paths./csrf.get (https://meta.stoplight.io/docs/spectral/docs/reference/openapi-rules.md#operation-description)
🪛 GitHub Check: Run Spectral
[warning] 62-62:
operation-description Operation "description" must be present and non-empty string. paths./csrf.get
[warning] 39-39:
operation-description Operation "description" must be present and non-empty string. paths./verify-email/confirm.get
[warning] 10-10:
operation-description Operation "description" must be present and non-empty string. paths./verify-email.post
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openapi.yaml` around lines 9 - 69, Add a detailed description field for each
operation to satisfy Spectral and provide clearer docs: for operationId
postVerifyEmail (POST /verify-email) add a description explaining that this
endpoint accepts a VerifyEmailRequest JSON body, sends a one-time verification
email to the provided address, optionally uses the redirect query param to build
the verification link, and returns 202 when the email dispatch is accepted; for
operationId getVerifyEmailConfirm (GET /verify-email/confirm) add a description
stating it validates the one-time token query param, completes login or account
verification and responds with a 303 redirect on success (or 400/401/500 as
documented); for operationId getCsrf (GET /csrf) add a description that the
endpoint issues a CSRF token cookie (no response body) and returns 204. Ensure
each description is placed under the operation's description field in the
OpenAPI spec.
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
openapi.yaml (1)
106-123:⚠️ Potential issue | 🟠 Major
X-CSRF-Token必須化に対する400が抜けています。生成された Echo wrapper は header 不在/不正で即
400を返しますが、この 3 operation の responses には400がありません。契約と生成サーバーの挙動がずれるので、BadRequestを追加したいです。Also applies to: 129-146, 153-170
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openapi.yaml` around lines 106 - 123, The OpenAPI operations that include the CsrfToken parameter (the blocks referencing components/parameters/CsrfToken and returning 201/500) are missing a 400 response; add a '400' response (preferably by referencing an existing components/responses/BadRequest or by defining a BadRequest response) to each of those operations so the spec matches the generated Echo wrapper which returns 400 for missing/invalid X-CSRF-Token; update the three operation response sections (the ones shown and the other two at the noted ranges) to include '400': $ref: '#/components/responses/BadRequest'.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openapi.yaml`:
- Around line 61-69: The /csrf GET operation (operationId: getCsrf) currently
returns a 204 with no Set-Cookie header, cookie name, or instructions for the
double-submit flow; update the OpenAPI spec to (1) document the Set-Cookie
response header including the cookie name (e.g., "CsrfToken"), attributes
(HttpOnly=false if client-readable, Secure, SameSite), and the cookie value
source, (2) include a response header definition for X-CSRF-Token (or describe
that the client must read the CsrfToken cookie and copy it to X-CSRF-Token) with
a schema string and example, and (3) add a short description in the operation
describing the double-submit sequence (server sets CsrfToken cookie, client
reads cookie and sends its value in X-CSRF-Token on state-changing requests) so
clients can implement the flow; apply the same changes to the other occurrence
referenced (lines 298-305 / corresponding operation).
- Around line 15-20: The query parameter named "redirect" currently only has
type:string and must be constrained to accept only relative paths like
VerifyEmailStartResponse.redirect; update the parameter definition for
"redirect" to use the same schema/pattern (and/or enum/format) as
VerifyEmailStartResponse.redirect so absolute URLs and protocol-relative URLs
are rejected, ensuring the request-side contract matches the response-side
constraint.
---
Outside diff comments:
In `@openapi.yaml`:
- Around line 106-123: The OpenAPI operations that include the CsrfToken
parameter (the blocks referencing components/parameters/CsrfToken and returning
201/500) are missing a 400 response; add a '400' response (preferably by
referencing an existing components/responses/BadRequest or by defining a
BadRequest response) to each of those operations so the spec matches the
generated Echo wrapper which returns 400 for missing/invalid X-CSRF-Token;
update the three operation response sections (the ones shown and the other two
at the noted ranges) to include '400': $ref:
'#/components/responses/BadRequest'.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: dcf276e2-3e6b-4d26-9ea4-5c8c14964b79
📒 Files selected for processing (2)
openapi.yamlserver/gen.go
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openapi.yaml`:
- Around line 80-81: The OpenAPI spec adds authentication (security: cookieAuth)
to GET /customer and requires X-CSRF-Token on three write endpoints but omits
failure responses; update the relevant operation objects (e.g., the GET
/customer operation with security: cookieAuth and each write operation that
checks X-CSRF-Token) to include appropriate error responses: add 401 and/or 403
responses for authentication/authorization failures matching implementation
behavior, and add 400 responses for missing/invalid CSRF tokens on the write
endpoints; ensure the response objects include a brief description and reference
any existing error schema used elsewhere so clients can see failure conditions.
- Around line 49-50: The 303 response for GET /verify-email/confirm lacks the
redirect Location and the Set-Cookie header that issues the checkin_csrf cookie
(required by the CsrfToken parameter); update the '303' response object to
include response headers: a Location header (string, example value pointing to
the redirect target used by your flow) and a Set-Cookie header (string,
documenting issuance of the checkin_csrf cookie including attributes like
HttpOnly, Secure, Path, SameSite and an example cookie value), and ensure the
description mentions the redirect plus cookie issuance so consumers implementing
the browser flow can rely on the redirect URL and the checkin_csrf cookie being
set.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: af7641d2-c6e5-463e-abed-15261f4281b7
📒 Files selected for processing (2)
openapi.yamlserver/gen.go
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
openapi.yaml (2)
111-121:/csrfもCache-Control: no-storeに揃えたいです。確認フロー側は
no-storeを返しているのに、CSRF cookie を配るGET /csrfだけ cache 抑止がありません。token 発行 endpoint の応答は stale token の再利用余地を減らすためにも non-cacheable にしておく方が安全です。📦 変更案
responses: '204': description: No Content headers: + Cache-Control: + description: ブラウザや中継に保存させない + schema: + type: string + example: no-store Set-Cookie: description: > `__Host-checkin_csrf` cookie を発行する。state-changing request では、この cookie の値を `X-CSRF-Token` header にそのままコピーして送る。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openapi.yaml` around lines 111 - 121, The /csrf response (operation for path "/csrf", response '204' that sets the Set-Cookie header) is missing a Cache-Control header; add a non-cacheable header entry under responses.'204'.headers named "Cache-Control" with a description and schema { type: string } and example "no-store" so the OpenAPI explicitly documents that this endpoint must return Cache-Control: no-store to prevent token caching.
267-271:invoice.paid用 endpoint に対して payload schema が広すぎます。
StripeEventが自由オブジェクトのままなので、POST /webhook/invoice-paidでもtype == invoice.paidやdata.objectの存在を仕様から保証できません。これだと生成型もmap[string]interface{}になり、この endpoint が前提にしている最小 shape を client / test 側で検証しづらくなります。🧩 変更案
StripeEvent: - description: Generic Stripe event payload + description: Stripe invoice.paid event payload type: object + required: + - id + - type + - data + properties: + id: + type: string + type: + type: string + enum: + - invoice.paid + data: + type: object + required: + - object + properties: + object: + type: object + additionalProperties: true additionalProperties: trueAlso applies to: 671-674
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openapi.yaml` around lines 267 - 271, The POST /webhook/invoice-paid endpoint currently references the overly-broad components/schemas/StripeEvent; narrow the request schema to a specific invoice-paid event shape by adding (or referencing) a new schema like InvoicePaidEvent that requires "type": "invoice.paid" and a non-empty "data.object" with the minimal invoice fields your handler needs (e.g., id, customer, amount_paid, status); update the openapi.yaml entry for the endpoint to use this new InvoicePaidEvent schema instead of StripeEvent so generated clients/tests get a concrete typed structure rather than map[string]interface{}.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openapi.yaml`:
- Around line 442-446: The OpenAPI spec defines securitySchemes.cookieAuth using
the __Host-checkin_session cookie but does not declare HTTPS-only transport in
servers; update the spec so cookieAuth's intended secure transport is explicit
by adding/ensuring at least one HTTPS server entry under servers (and, if
retaining an HTTP server, separate it clearly as a development server), and
annotate or document the securitySchemes.cookieAuth (and the
__Host-checkin_session name) to indicate it requires secure (Secure, SameSite,
Host-only) cookie semantics; modify the top-level servers list and the
securitySchemes.cookieAuth description to reflect this requirement.
---
Nitpick comments:
In `@openapi.yaml`:
- Around line 111-121: The /csrf response (operation for path "/csrf", response
'204' that sets the Set-Cookie header) is missing a Cache-Control header; add a
non-cacheable header entry under responses.'204'.headers named "Cache-Control"
with a description and schema { type: string } and example "no-store" so the
OpenAPI explicitly documents that this endpoint must return Cache-Control:
no-store to prevent token caching.
- Around line 267-271: The POST /webhook/invoice-paid endpoint currently
references the overly-broad components/schemas/StripeEvent; narrow the request
schema to a specific invoice-paid event shape by adding (or referencing) a new
schema like InvoicePaidEvent that requires "type": "invoice.paid" and a
non-empty "data.object" with the minimal invoice fields your handler needs
(e.g., id, customer, amount_paid, status); update the openapi.yaml entry for the
endpoint to use this new InvoicePaidEvent schema instead of StripeEvent so
generated clients/tests get a concrete typed structure rather than
map[string]interface{}.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8bfe3798-40db-472c-9a3b-816294b3502d
📒 Files selected for processing (2)
openapi.yamlserver/gen.go
Comment on lines
+442
to
+446
| securitySchemes: | ||
| cookieAuth: | ||
| type: apiKey | ||
| in: cookie | ||
| name: __Host-checkin_session |
There was a problem hiding this comment.
cookieAuth の transport 条件を仕様に出しておきたいです。
__Host-checkin_session を前提にしたのに、この spec には HTTPS-only な servers: がなく、契約上は平文の base URL でも成立して見えます。secure cookie を本当に前提にするなら、少なくとも HTTPS の server entry を明示して、HTTP を残す場合も開発用と分けておいた方が安全です。
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openapi.yaml` around lines 442 - 446, The OpenAPI spec defines
securitySchemes.cookieAuth using the __Host-checkin_session cookie but does not
declare HTTPS-only transport in servers; update the spec so cookieAuth's
intended secure transport is explicit by adding/ensuring at least one HTTPS
server entry under servers (and, if retaining an HTTP server, separate it
clearly as a development server), and annotate or document the
securitySchemes.cookieAuth (and the __Host-checkin_session name) to indicate it
requires secure (Secure, SameSite, Host-only) cookie semantics; modify the
top-level servers list and the securitySchemes.cookieAuth description to reflect
this requirement.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
新機能
改善
削除
変更