Skip to content

feat: /list/invoicesと/invoiceを/invoicesに統一 #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
reiroop wants to merge 1 commit into
base: main
Choose a base branch
from
+186 −187
Open

feat: /list/invoicesと/invoiceを/invoicesに統一 #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 42 additions & 43 deletions openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
openapi: 3.1.0

Check warning on line 1 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

oas3-api-servers       OpenAPI "servers" must be present and non-empty array.

info:

Check warning on line 3 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

info-contact           Info object must have "contact" object.                        info
title: Checkin API
Expand All @@ -7,7 +7,7 @@

paths:
/verify-email:
post:

Check warning on line 10 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

operation-description  Operation "description" must be present and non-empty string.  paths./verify-email.post
summary: isct メールアドレスの確認メールを送信
tags:
- Auth
Expand All @@ -32,7 +32,7 @@
'500':
$ref: '#/components/responses/InternalServerError'
/verify-email/confirm:
get:

Check warning on line 35 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

operation-description  Operation "description" must be present and non-empty string.  paths./verify-email/confirm.get
summary: メール確認トークンの確認ページを表示
tags:
- Auth
Expand Down Expand Up @@ -64,7 +64,7 @@
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
post:

Check warning on line 67 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

operation-description  Operation "description" must be present and non-empty string.  paths./verify-email/confirm.post
summary: メール確認トークンを消費してログインを完了
tags:
- Auth
Expand Down Expand Up @@ -103,7 +103,7 @@
'500':
$ref: '#/components/responses/InternalServerError'
/csrf:
get:

Check warning on line 106 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

operation-description  Operation "description" must be present and non-empty string.  paths./csrf.get
summary: CSRF トークン用 cookie を発行
tags:
- Auth
Expand Down Expand Up @@ -217,7 +217,48 @@
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
/invoice:
/invoices:
get:

Check warning on line 221 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

operation-description  Operation "description" must be present and non-empty string.  paths./invoices.get
summary: 請求書由来の入金一覧を取得
tags:
- Invoice
operationId: getInvoices
Comment on lines +221 to +225
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

GET /invoices に description を追加してください。

summary だけだと Spectral の operation-description に引っかかるので、このエンドポイントだけ生成ドキュメントの情報量が落ちます。

📝 追加例 
   /invoices:
     get:
       summary: 請求書由来の入金一覧を取得
+      description: 条件に一致する請求書由来の入金一覧を取得
       tags:
         - Invoice
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
get:
summary: 請求書由来の入金一覧を取得
tags:
- Invoice
operationId: getInvoices
get:
summary: 請求書由来の入金一覧を取得
description: 条件に一致する請求書由来の入金一覧を取得
tags:
- Invoice
operationId: getInvoices
🧰 Tools
🪛 GitHub Check: Run Spectral

[warning] 221-221:
operation-description Operation "description" must be present and non-empty string. paths./invoices.get

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openapi.yaml` around lines 221 - 225, The GET /invoices operation
(operationId: getInvoices) is missing a description, which triggers Spectral's
operation-description rule; add a descriptive "description" field under the get
operation for this endpoint (next to summary, tags, operationId) that explains
what the endpoint returns, any important query parameters or filters, and
expected behavior/usage so the generated docs include sufficient detail.

parameters:
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/SubscriptionId'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
- name: status
description: 請求書ステータス
in: query
schema:
type: string
enum:
- draft
- open
- paid
- uncollectible
- void
- name: collection_method
description: 請求書の支払い方法
in: query
schema:
type: string
enum:
- charge_automatically
- send_invoice
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'403':
$ref: '#/components/responses/Forbidden'
'500':
Comment on lines +251 to +260
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

400 BadRequest をレスポンス仕様に含めてください。

このエンドポイントは limit などのクエリバインド失敗時に生成 wrapper 側で 400 を返しますが、OpenAPI には 200/403/500 しか載っていません。実装と契約がずれるので、クライアント生成やエラーハンドリングの前提がずれます。

🧩 追記例 
       responses:
         '200':
           description: OK
           content:
             application/json:
               schema:
                 $ref: '`#/components/schemas/Invoice`'
+        '400':
+          $ref: '`#/components/responses/BadRequest`'
         '403':
           $ref: '`#/components/responses/Forbidden`'
         '500':
           $ref: '`#/components/responses/InternalServerError`'
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'403':
$ref: '#/components/responses/Forbidden'
'500':
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '`#/components/schemas/Invoice`'
'400':
$ref: '`#/components/responses/BadRequest`'
'403':
$ref: '`#/components/responses/Forbidden`'
'500':
$ref: '`#/components/responses/InternalServerError`'
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openapi.yaml` around lines 251 - 260, The OpenAPI response list for this
endpoint is missing a 400 response which causes a spec/implementation mismatch;
add a '400' response entry under the responses block (alongside '200', '403',
'500') that either references an existing reusable response (e.g. $ref:
'`#/components/responses/BadRequest`') or defines an inline BadRequest
schema/body, so client generation and error handling match the wrapper behavior
for query bind failures (e.g. when validating limit); update the responses
section that currently references the Invoice schema to include this new '400'
entry.

$ref: '#/components/responses/InternalServerError'
post:
summary: Invoice を作成
description: session cookie または信頼済み proxy auth が必要。`X-CSRF-Token` も必須
Expand Down Expand Up @@ -247,7 +288,7 @@
'500':
$ref: '#/components/responses/InternalServerError'
/webhook/invoice-paid:
post:

Check warning on line 291 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

operation-description  Operation "description" must be present and non-empty string.  paths./webhook/invoice-paid.post
summary: Webhook の invoice.paid イベントを受け取る
tags:
- Webhook
Expand All @@ -272,51 +313,9 @@
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/list/invoices:
get:
summary: 請求書由来の入金一覧を取得
tags:
- List
operationId: getInvoices
parameters:
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/SubscriptionId'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
- name: status
description: 請求書ステータス
in: query
schema:
type: string
enum:
- draft
- open
- paid
- uncollectible
- void
- name: collection_method
description: 請求書の支払い方法
in: query
schema:
type: string
enum:
- charge_automatically
- send_invoice
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'

/list/checkout-sessions:
get:

Check warning on line 318 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

operation-description  Operation "description" must be present and non-empty string.  paths./list/checkout-sessions.get
summary: オンライン決済ページ由来の入金一覧を取得
tags:
- List
Expand Down Expand Up @@ -353,7 +352,7 @@
'500':
$ref: '#/components/responses/InternalServerError'
/admin:
get:

Check warning on line 355 in openapi.yaml

View workflow job for this annotation

GitHub Actions / Run Spectral 

operation-description  Operation "description" must be present and non-empty string.  paths./admin.get
summary: 管理者の一覧を取得
tags:
- Admin
Expand Down
Loading
Loading