Open APIによる仕様書をブラッシュアップ

[ToYama170402]

変更内容

変更の種類

• バグ修正（Bug fix）
• 新機能（New feature）
• 破壊的変更（Breaking change）
• [ x] ドキュメント更新（Documentation update）
• リファクタリング（Refactoring）
• パフォーマンス改善（Performance improvement）
• テスト追加・修正（Test update）
• その他（Other）

関連Issue

Closes #

変更の詳細

テスト

• 既存のテストが通ることを確認
• 新しいテストを追加
• 手動でテスト実施

テスト内容

チェックリスト

• コードが正常に動作することを確認した
• 適切なコメントを追加した（必要に応じて）
• ドキュメントを更新した（必要に応じて）
• 新しい警告が発生していないことを確認した
• 依存関係の追加や更新がある場合、その理由を説明した

スクリーンショット

その他

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
rishu-app	Error		Dec 31, 2025 1:44pm

[gemini-code-assist]

Summary of Changes

Hello @ToYama170402, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

このプルリクエストは、syllabus-backendのAPI仕様をOpenAPI形式で文書化することを目的としています。これにより、コース情報の取得、作成、更新、削除を行うためのエンドポイントと、関連するデータモデルが明確に定義され、APIの利用者がシステムとの連携方法を容易に理解できるようになります。APIの構造とデータ形式が標準化された形で提供されるため、開発効率の向上と誤解の防止に貢献します。

Highlights

• API仕様の新規追加: Rishu Syllabus APIのOpenAPI仕様を定義するsyllabus-backend/doc/api.ymlファイルが新しく追加されました。
• コース関連エンドポイントの定義: /coursesパスに対するコースの一覧取得（GET）と一括作成（POST）、および/courses/{courseId}パスに対する特定のコースの取得（GET）、更新（PUT）、削除（DELETE）の操作が詳細に記述されています。
• 詳細なデータスキーマ定義: Course、CourseResponse、Instructor、Schedule、Facultyといった主要なデータモデルが、プロパティ、型、説明、必須フィールド、および日本語の列挙型（学域・学類名、曜日など）を含めて定義されています。

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

このプルリクエストでは、シラバスAPIの仕様がOpenAPI形式で新たに追加されました。APIのエンドポイントとデータモデルが明確に定義されており、プロジェクトにとって素晴らしい追加です。レビューを通して、セキュリティ、保守性、一貫性の観点からいくつかの改善点を提案させていただきました。具体的には、HTTPSの使用、共通スキーマの利用による重複の削減、エラーレスポンスの拡充、そして必須フィールドの見直しなどです。詳細については、各コメントをご確認ください。

I am having trouble creating individual review comments. Click here to see my feedback.

syllabus-backend/doc/api.yml (9)

サーバーのURLがhttpで定義されています。本番環境など、セキュアな通信が求められる場面では、通信を暗号化するためにhttpsを使用することが強く推奨されます。
また、APIに認証・認可の仕組みがある場合は、securitySchemesとsecurityを用いて仕様に明記するべきです。

例えば、以下のように複数のサーバーを定義したり、APIキー認証を追加したりできます。

servers:
  - url: https://api.example.com
    description: Production server
  - url: http://localhost:8080
    description: Local development server

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

  - url: https://{apiHost}:8080

syllabus-backend/doc/api.yml (46-72)

facultyパラメータのenumがここで定義されていますが、components/schemas/Facultyスキーマ内(L486-L506)でも同様のenumが定義されています。
このように定義が重複していると、将来enumの値を更新する際に、複数箇所を修正する必要があり、メンテナンス性が低下します。
componentsにFacultyNameのような共通スキーマを定義し、$refで参照することで、重複をなくし、一元管理することをお勧めします。departmentパラメータについても同様です。

例:

components:
  schemas:
    FacultyName:
      type: string
      enum:
        - 先導学類
        - ...
# ...
paths:
  /courses:
    get:
      parameters:
        - name: faculty
          in: query
          schema:
            $ref: '#/components/schemas/FacultyName'

syllabus-backend/doc/api.yml (184-207)

courseIdのフォーマットが不正な場合（例：整数でない）など、クライアントからのリクエストが不正な場合に返される400 Bad Requestレスポンスが定義されていません。
POST /coursesで定義されているような、エラー詳細を含む400レスポンスを各エンドポイントで定義することが推奨されます。
一貫性を保つために、共通のエラーレスポンススキーマをcomponentsに定義し、それを$refで参照する方法が効果的です。

# components/schemas に共通エラーレスポンスを定義
    ErrorResponse:
      type: object
      properties:
        error:
          type: string

# 各エンドポイントの responses で参照
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

syllabus-backend/doc/api.yml (291)

API仕様内のdescriptionフィールドで、英語と日本語が混在しています（例：summaryは英語、ここのdescriptionは日本語）。
仕様の一貫性を保つため、主要な言語を一つ（APIのキーワードが英語であるため、英語が望ましい）に統一することをお勧めします。日本語は補足情報として括弧内に記述するなどのルールを設けると良いでしょう。

          description: "Course Numbering (科目ナンバリング)"

syllabus-backend/doc/api.yml (354-367)

Courseスキーマにおいて、lectureRoomInfo(L366)やenglishUrl(L362)など、多くのフィールドがrequiredとされています。
しかし、実際のデータでは講義室が「未定」であったり、英語のシラバスURLが存在しない場合も考えられます。これらのフィールドを必須にすると、該当する科目の登録や更新ができなくなる可能性があります。
本当に常に必須であるフィールドのみをrequiredとし、それ以外は任意（optional）にすることを検討してください。

syllabus-backend/doc/api.yml (369-443)

CourseResponseスキーマは、courseIdが追加されている点を除き、Courseスキーマとほぼ同じ内容です。これにより多くの重複が生じており、メンテナンス性が低下しています。
OpenAPIのallOfを使用してCourseスキーマを継承・拡張することで、この重複をなくすことができます。

また、現在のCourseResponseにはrequiredプロパティがありません。APIが常に完全なコース情報を返すのであれば、Courseから継承したプロパティとcourseIdをrequiredに指定すべきです。

    CourseResponse:
      allOf:
        - $ref: '#/components/schemas/Course'
        - type: object
          required:
            - courseId
          properties:
            courseId:
              description: Unique identifier for the course (独自ID)
              type: integer
              readOnly: true