---
name: jabrena-701-technologies-openapi
description: "Use when you need framework-agnostic OpenAPI 3.x guidance — spec structure, metadata and versioning, paths and operations, reusable schemas, security schemes, examples, documentation quality, contract validation (e.g. Spectral), breaking-change awareness, and handoffs to codegen — without choosing Spring Boot, Quarkus, or Micronaut. This should trigger for requests such as Review an OpenAPI; Improve an OpenAPI; Improve API contract; Improve API schema design. Part of Plinth Toolkit"
license: "Apache-2.0"
metadata:
  decimalai-skill-id: "1a89ae9b-94fc-421a-8778-83b6247d9861"
  decimalai-version-id: "4fd70380-263f-4990-821a-f7de26291cb7"
  decimalai-version: "1"
  decimalai-body-sha256: "3cf5cef0ed5f81ad48f7fb145f7f3317077e78df3c90ca97aa0c3777b4348e6e"
  decimalai-name: "jabrena/701-technologies-openapi"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "coding"
  decimalai-source: "https://app.decimal.ai/s/jabrena-701-technologies-openapi@1/SKILL.md"
---
# OpenAPI 3.x best practices

Help teams produce maintainable **OpenAPI 3.x** contracts that stay aligned with HTTP semantics and consumer needs.

**What is covered in this Skill?**

- Document structure: `openapi`, `info`, `servers`, `tags`, and consistent resource grouping
- Path and operation design: parameters, request bodies, response matrices, `operationId`, status codes
- Reusable `components` (schemas, parameters, responses, security schemes) and examples
- Validation and CI: spec linting, breaking-change checks, pre-codegen gates
- Security modeling in the contract (schemes, scopes, global vs operation security)
- Clear boundaries between contract-first design and runtime implementation concerns

**Scope:** Contract-first quality only. Focus this skill on OpenAPI design, quality, and governance guidance.

## Constraints

Keep recommendations at the OpenAPI layer unless the user explicitly asks for Java framework integration. After editing this repository's XML sources, regenerate skills and verify the build.

- **MANDATORY**: Run `./mvnw compile` or `mvn compile` before proposing Java or Maven changes in the same change set
- **FRAMEWORK**: Keep guidance contract-centric; do not prescribe framework-specific controller wiring or runtime exposure details
- **FUZZING**: Keep fuzzing guidance high-level and contract-focused without linking to external skill identifiers
- **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` before promoting changes
- **EDGE CASE**: If the user goal is ambiguous, stop and ask a clarifying question before editing files or running project-wide commands
- **EDGE CASE**: If required context, files, credentials, or tools are missing, report the blocker explicitly and ask whether to proceed with setup or fallback guidance
- **EDGE CASE**: If requested changes conflict with project constraints or safety boundaries, explain the conflict and ask for user confirmation on the preferred trade-off

## When to use this skill

- Review an OpenAPI
- Improve an OpenAPI
- Improve API contract
- Improve API schema design
- Validate an OpenAPI spec

## Workflow

1. **Read reference and assess project context**

Read `references/701-technologies-openapi.md` and inspect current API/context artifacts before proposing changes.

2. **Gather scope and decide target improvements**

Identify requested outcomes, constraints, and the minimum safe set of changes to apply.

3. **Apply technology-aligned changes**

Implement or refactor artifacts following the reference patterns and project conventions.

4. **Run verification and report results**

Execute appropriate checks and summarize what changed, what was verified, and any follow-up actions.

## Reference

For detailed guidance, examples, and constraints, see [references/701-technologies-openapi.md](references/701-technologies-openapi.md).