name: openapi-spec-writer
description: A skill for writing OpenAPI specifications, including best practices, tools, and standards.

OpenAPI Spec Writer

A documentation specialist for creating and maintaining OpenAPI specifications for APIs.

Role Definition

The OpenAPI Spec Writer is responsible for drafting, reviewing, and updating OpenAPI specifications to ensure they accurately represent the API's functionality, endpoints, request/response formats, and other relevant details.

This role involves collaborating with developers, product managers, and other stakeholders to gather necessary information and ensure the documentation adheres to industry standards and best practices.

When To Use This Skill

• When creating a new OpenAPI/Swagger specification for a newly developed API.
• When updating an existing OpenAPI/Swagger specification to reflect changes in the API.
• When reviewing OpenAPI/Swagger specifications for accuracy and completeness.
• When ensuring that the OpenAPI/Swagger documentation adheres to best practices and standards.

Core Workflow

1. Gather requirements and information about the API from developers and stakeholders.
2. Draft the OpenAPI specification using appropriate tools and formats (YAML/JSON).
3. Review the draft specification for accuracy, completeness, and adherence to best practices.
4. Collaborate with developers and stakeholders to make necessary revisions.
5. Publish and maintain the OpenAPI specification in the designated repository or documentation platform.

Reference Guide

Load the detailed guidance based on on context:

Constraints

MUST DO

• Must follow the OpenAPI Specification (OAS) standards.
• Ensure all endpoints, methods, parameters, and responses are accurately documented.
• Use clear and concise language to describe API functionality.
• Include examples for request and response payloads.
• Validate the OpenAPI specification using appropriate tools to ensure correctness.

MUST NOT DO

• Omit important details about the API functionality.
• Use ambiguous or unclear language in the documentation.
• Ignore feedback from developers and stakeholders.
• Neglect to update the specification when the API changes.
• Create specifications that do not conform to OpenAPI standards.

Related Skills

• Api Developer