ringapi-field-descriptions
by LerianStudio
ringapi-field-descriptionsは、other分野における実用的なスキルです。複雑な課題への対応力を強化し、業務効率と成果の質を改善します。
Manusで実行SKILL.md
name: ring:api-field-descriptions description: | Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases.
trigger: |
- Writing API field documentation
- Documenting request/response schemas
- Creating data model documentation
skip_when: |
- Writing conceptual docs → use writing-functional-docs
- Full API endpoint docs → use writing-api-docs
related: complementary: [writing-api-docs]
API Field Descriptions
Field descriptions are the most-read part of API documentation. Users scan for specific fields and need clear, consistent information.
Field Description Structure
Every field description answers: What is it? (purpose), What type? (data type), Required? (mandatory), Constraints? (limits/validations), Example? (valid data)
Table Format (Preferred)
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | uuid | — | The unique identifier of the Account |
| name | string | Yes | The display name of the Account (max 255 chars) |
| status | enum | — | Account status: `ACTIVE`, `INACTIVE`, `BLOCKED` |
Note: Use — for response-only fields (not applicable for requests).
For nested objects: status.code, status.description
Description Patterns by Type
| Type | Pattern | Example |
|---|---|---|
| UUID | "The unique identifier of the [Entity]" | id: uuid — The unique identifier of the Account |
| String | "[Purpose] (constraints)" | code: string — The asset code (max 10 chars, uppercase, e.g., "BRL") |
| String (format) | "[Purpose] (format example)" | email: string — Email address (e.g., "user@example.com") |
| Enum | "[Purpose]: val1, val2, val3" | type: enum — Asset type: \currency`, `crypto`, `commodity`` |
| Boolean | "If true, [what happens]. Default: [value]" | allowSending: boolean — If \true`, sending permitted. Default: `true`` |
| Integer | "[Purpose] (range)" | scale: integer — Decimal places (0-18) |
| Timestamp | "Timestamp of [event] (UTC)" | createdAt: timestamptz — Timestamp of creation (UTC) |
| Object (jsonb) | "[Purpose] including [fields]" | status: jsonb — Status information including code and description |
| Array | "List of [what it contains]" | operations: array — List of operations in the transaction |
Required vs Optional
In Requests:
Yes= Must be providedNo= OptionalConditional= Required in specific scenarios (explain in description)
In Responses: Use — (response fields are always returned or null)
Special Field Documentation
| Pattern | Format |
|---|---|
| Default values | "Results per page. Default: 10" |
| Nullable fields | "Soft deletion timestamp, or null if not deleted" |
| Deprecated fields | "[Deprecated] Use route instead" |
| Read-only fields | "Read-only. Generated by the system" |
| Relationships | "References an Asset code. Must exist in the Ledger" |
Writing Good Descriptions
| Don't | Do |
|---|---|
| "The name" | "The display name of the Account" |
| "Status info" | "Account status: ACTIVE, INACTIVE, BLOCKED" |
| "A number" | "Balance version, incremented with each transaction" |
| "The code" | "The asset code (max 10 chars, uppercase)" |
| "The timestamp" | "Timestamp of creation (UTC)" |
Quality Checklist
- Description explains the field's purpose
- Data type is accurate
- Required/optional status is clear
- Constraints documented (max length, valid values)
- Default value noted (if optional)
- Nullable behavior explained (if applicable)
- Deprecated fields marked
- Read-only fields indicated
- Relationships to other entities clear
- Example values realistic
スコア
総合スコア
リポジトリの品質指標に基づく評価
SKILL.mdファイルが含まれている
ライセンスが設定されている
100文字以上の説明がある
GitHub Stars 100以上
3ヶ月以内に更新がある
10回以上フォークされている
オープンIssueが50未満
プログラミング言語が設定されている
1つ以上のタグが設定されている
レビュー
レビュー機能は近日公開予定です