agentsclimarketplace

Documentation

Skill pluginagentmarketplace/custom-plugin-api-design/skills/documentation

API documentation with OpenAPI and developer portalsFrom its SKILL.md

Install
npx -y skills add pluginagentmarketplace/custom-plugin-api-design --skill documentation

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.2 KB, as published. Nobody here has run it

API Documentation Skill

Purpose

Create comprehensive API documentation.

OpenAPI 3.1 Structure

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
  description: |
    API description with **markdown** support.

    ## Authentication
    Use Bearer tokens.

servers:
  - url: https://api.example.com
    description: Production

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      tags: [Users]
      parameters:
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string

Code Examples

Multiple Languages

# In OpenAPI
paths:
  /users:
    post:
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST https://api.example.com/users \
              -H "Authorization: Bearer TOKEN" \
              -d '{"name": "John"}'
        - lang: python
          source: |
            import requests
            requests.post('https://api.example.com/users',
              headers={'Authorization': 'Bearer TOKEN'},
              json={'name': 'John'})
        - lang: javascript
          source: |
            await fetch('https://api.example.com/users', {
              method: 'POST',
              headers: { 'Authorization': 'Bearer TOKEN' },
              body: JSON.stringify({ name: 'John' })
            });

SDK Generation

# Generate TypeScript SDK
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./sdk

# Generate Python SDK
openapi-generator generate \
  -i openapi.yaml \
  -g python \
  -o ./sdk-python

Changelog Format

# Changelog

## [1.2.0] - 2024-12-30

### Added
- `GET /users/export` endpoint

### Changed
- `POST /users` now returns 201

### Deprecated
- `GET /users/:id/profile` (use `/users/:id`)

### Fixed
- Pagination cursor encoding

Unit Test Template

import { validate } from '@apidevtools/swagger-parser';

describe('OpenAPI Spec', () => {
  it('should be valid OpenAPI 3.1', async () => {
    const api = await validate('./openapi.yaml');
    expect(api.openapi).toMatch(/^3\.1\./);
  });

  it('should have examples for all endpoints', async () => {
    const api = await validate('./openapi.yaml');
    Object.values(api.paths).forEach(path => {
      Object.values(path).forEach(operation => {
        if (operation.responses?.['200']) {
          expect(operation.responses['200'].content)
            .toHaveProperty('application/json.examples');
        }
      });
    });
  });
});

Troubleshooting

IssueCauseSolution
Spec validation failsInvalid syntaxUse spectral linter
SDK types wrongSchema mismatchRegenerate from spec
Missing examplesIncomplete docsAdd request/response examples

Quality Checklist

  • OpenAPI spec validates
  • All endpoints documented
  • Request/response examples
  • Error responses documented
  • Authentication explained
  • SDKs generated and tested

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.