skills.rest
getsentry
getsentryOFFICIAL
Explore all skills by this author →
Website𝕏@sentryGitHub

document-api-endpoint

Document and type Sentry API endpoints with drf-spectacular OpenAPI schemas.

974|51|Updated Jan 5, 2026
Search Tags:#OpenAPI#api documentation#Sentry#typedDict#drf-spectacular#extend_schema#type drift
One-click install
npx skills add https://github.com/getsentry/skills --skill document-api-endpoint
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: document-api-endpoint
Source: https://github.com/getsentry/skills/tree/main/skills/document-api-endpoint
Command: npx skills add https://github.com/getsentry/skills --skill document-api-endpoint

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Writing accurate OpenAPI documentation for Sentry API endpoints is error-prone: declared schemas often drift from what endpoints actually return, legacy api-docs JSON files conflict with drf-spectacular decorators, and promoting endpoints to PUBLIC involves non-obvious steps. This Skill captures those lessons so the declared schema matches runtime behavior.

Core Features & Use Cases

  • @extend_schema Authoring: Write or fix class-level and method-level @extend_schema decorators with correct tags, operation IDs, parameters, responses, and examples, reusing canonical entries from src/sentry/apidocs/parameters.py.
  • Response Typing & Drift Correction: Specify response TypedDicts following the XxxResponseOptional(TypedDict, total=False) mixin pattern, distinguish nullable (T | None) from absent (NotRequired[T]) fields, and fix type drift by diffing live endpoint responses against declared types.
  • Legacy Migration & Public Promotion: Migrate legacy api-docs/paths*.json files all-or-nothing per path, and promote PRIVATE/EXPERIMENTAL endpoints to PUBLIC by bumping publish_status, setting owner = ApiOwner.<TEAM>, and updating the ownership allowlist.
  • Use Case: You need to make an internal Sentry endpoint public. The Skill guides you through typing the response, validating with make build-api-docs and pnpm run validate-api-examples, and flipping the publish status in one coherent change.

Quick Start

Ask the agent to document and type a specific Sentry API endpoint with drf-spectacular, fix any type drift against the live response, and validate the generated OpenAPI spec.

Frequently Asked Questions about document-api-endpoint

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add OpenAPI documentation to a Sentry API endpoint?▼

Add a class-level @extend_schema with tags from OPENAPI_TAGS, then a method-level @extend_schema with operation_id, parameters, responses, and examples. Reuse entries from src/sentry/apidocs/parameters.py and examples, set owner = ApiOwner.<TEAM>, then validate with make build-api-docs.

How do I fix type drift between a declared schema and the actual API response?▼

Hit the live endpoint with a real token and diff the returned keys and types against your TypedDict. Watch for floats returned as counts, IDs emitted as strings, and nested types with wrong field counts, then correct the declared type to match runtime behavior.

What is the difference between nullable and NotRequired fields in Sentry response TypedDicts?▼

T | None means the key is always present but its value may be null. NotRequired[T] means the key is only set under a condition, such as an expand query parameter. Follow the XxxResponseOptional(TypedDict, total=False) mixin pattern.

Why do legacy api-docs JSON methods disappear after adding @extend_schema?▼

drf-spectacular's APPEND_PATHS does not merge HTTP methods, so once any method on a path uses @extend_schema, all legacy methods on that path vanish. Migrate every method on the path in one commit and delete both the JSON file and its $ref in api-docs/openapi.json.

How do I promote a Sentry API endpoint from PRIVATE to PUBLIC?▼

Bump publish_status for the method to PUBLIC, set owner = ApiOwner.<TEAM>, and remove the method from API_OWNERSHIP_ALLOWLIST_DONT_MODIFY in the same change. Deprecate redundant old versions first, and note any scope widening in the PR.

Related Skills

Explore More Software Engineering Skills→
benediktmsbenediktms

overmind-reference

Map Overmind modes, agents, MCP endpoints, and configuration for orchestration tasks.

Community
Intermediate
getsentrygetsentry
246

sentry-sdk-upgrade

Upgrade Sentry JavaScript SDK across major versions with migration steps.

Official
Advanced
shinnytechshinnytech

auth-implementation-patterns

Implement JWT, OAuth2, session, and RBAC authentication patterns.

Official
Advanced
Arize-aiArize-ai
1.2k

js-docs-sync

Verify and update hand-written docs/ documentation in JS packages against source code.

Official
Intermediate