Cursor rule

1---
2description:
3globs:
4alwaysApply: false
5---
6## OpenAPI Specification Management Rule
7 
8*This rule guides the creation and maintenance of the `docs/openapi.yaml` file.*
9 
10## File Existence Check
11 
12Before editing, determine which related docs already exist:
13 
14```bash
15ls . docs
16```
17 
18Use this information to inform the following steps.
19 
20### Core Directive
21Create and maintain an `docs/openapi.yaml` file, defining an OpenAPI specification (v3.0.x or 3.1.x). Operate based on information from `NOTES.md`, `docs/PRD.md`, `docs/TECH_STACK.md`, and the existing `docs/openapi.yaml` (if present), ensuring adherence to the OpenAPI structure outlined below.
22 
23### Strict Limitations
24- **File Operations:** Only read `NOTES.md`, `docs/PRD.md`, `docs/TECH_STACK.md`, `docs/openapi.yaml` (or equivalents), and read/write to `docs/openapi.yaml`. Do not interact with other files.
25- **Output Format:** Your entire output must be the content of the `docs/openapi.yaml` file itself.
26- **Communication:** You are forbidden from generating any conversational output, commentary, preamble, or summaries outside of the `docs/openapi.yaml` file.
27- **User Interaction (within `docs/openapi.yaml`):** You do not directly converse with the user. If sections of the `docs/openapi.yaml` are incomplete or require clarification, you will indicate this *within the `docs/openapi.yaml` file* using a specific YAML comment format.
28 
29### OpenAPI Specification Structure and Content Source
30The `docs/openapi.yaml` file must follow the structure below, derived from the "OpenAPI Specification Outline" questions. Aim for OpenAPI version 3.0.x or 3.1.x.
31 
32#### OpenAPI Specification Outline (Source for `docs/openapi.yaml` Structure and TODOs)
33 
341.  **OpenAPI Version & Basic Information (`openapi`, `info` block):**
35    - Specify the OpenAPI version (e.g., `openapi: 3.0.3`).
36    - **Title (`info.title`):** What is the official title for this API? (Source: `docs/PRD.md` - Project Name/Title. Example: "Customer Data API").
37    - **Version (`info.version`):** What is the current version of this API specification (e.g., "1.0.0", "v2.1-beta")?
38    - **Description (`info.description`):** Provide a brief description of the API's purpose and capabilities. (Source: `docs/PRD.md` - Project Purpose/Core Functionality. Example: "API for managing customer profiles and order history.").
39    - **(Optional) Contact (`info.contact`):**
40        - `name`: Contact person/team name (e.g., "API Support Team").
41        - `url`: URL to a support page or contact form.
42        - `email`: Contact email address (e.g., "apisupport@example.com").
43    - **(Optional) License (`info.license`):**
44        - `name`: SPDX license identifier (e.g., "Apache 2.0", "MIT").
45        - `url`: Link to the full license text.
46 
472.  **Server Configuration (`servers` block):**
48    - What are the base URLs for accessing the API? (Source: `docs/TECH_STACK.md` - Infrastructure & Deployment. Examples: `https://api.example.com/v1`, `https://sandbox.api.example.com/v1`).
49    - For each server, provide:
50        - `url`: The server URL.
51        - `description`: A human-readable description (e.g., "Production Server", "Sandbox Environment").
52 
533.  **Global Security Definitions (`components.securitySchemes` & `security` block):**
54    - What authentication/authorization methods will this API use? (Source: `docs/TECH_STACK.md` - Security Considerations. Examples: API Key, OAuth2, JWT Bearer Token).
55    - Define each scheme under `components.securitySchemes`:
56        - **API Key Example (`apiKeyAuth`):**
57            - `type: apiKey`
58            - `in: header` (or `query`, `cookie`)
59            - `name: X-API-KEY` (the name of the header or query parameter)
60        - **OAuth2 Example (`oauth2Auth`):**
61            - `type: oauth2`
62            - `flows`: Define one or more flows (e.g., `authorizationCode`, `clientCredentials`).
63                - `authorizationCode`:
64                    - `authorizationUrl: https://auth.example.com/oauth/authorize`
65                    - `tokenUrl: https://auth.example.com/oauth/token`
66                    - `scopes`: Define available scopes (e.g., `read:profile`, `write:orders`).
67    - If security applies globally to most/all endpoints, define it under the top-level `security` block. (Example: `security: - apiKeyAuth: []`).
68 
694.  **Tags for Grouping Operations (`tags` block):**
70    - What are the main functional groupings or resource categories for your API endpoints? (Source: `docs/PRD.md` - Key Features/Modules. Examples: "Users", "Products", "Orders").
71    - For each tag, provide:
72        - `name`: The tag name (e.g., "UserManagement").
73        - `description`: A brief explanation of the tag (e.g., "Operations related to user accounts and profiles").
74 
755.  **Reusable Schemas (`components.schemas` block):**
76    - What are the common data models (objects) that will be used in request and response bodies? (Source: `docs/PRD.md` - Key Features, Data Models; `docs/TECH_STACK.md` - Database for entities. Examples: `User`, `Product`, `Order`, `ErrorResponse`).
77    - For each schema (e.g., `User`):
78        - `type: object`
79        - `properties`: Define its fields.
80            - For each property (e.g., `id`, `username`, `email`, `status`):
81                - `type`: (e.g., string, integer, boolean)
82                - `format`: (e.g., uuid, email, int64) (Optional)
83                - `description`: (A brief explanation of the property) (Optional)
84                - `example`: (A sample value) (Optional)
85 
86After outputting the full `docs/openapi.yaml` file, give a brief executive summary outlining the main endpoints or components you defined. This summary should not be included inside the YAML file itself.
87