Index of every page on this site: llms.txt
All skills
jeremylongshore avatar

/generating-api-contracts

@820dfc8
Run it yourself

Generate API contracts and OpenAPI specifications from code or design documents. Use when documenting API contracts and specifications. Trigger with phrases like "generate API contract", "create OpenAPI spec", or "document API contract".

Use this Skill: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/generating-api-contracts

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesexamples.md

≈1.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

API Contract Generation Examples

OpenAPI 3.1 Specification

openapi: 3.1.0
info:
  title: User Management API
  version: 2.0.0
servers:
  - url: https://api.example.com/v2

paths:
  /users:
    get:
      operationId: listUsers
      summary: List users with pagination
      parameters:
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: Paginated user list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
    post:
      operationId: createUser
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/ValidationError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    User:
      type: object
      required: [id, name, email, status]
      properties:
        id: { type: string, pattern: '^usr_[a-zA-Z0-9]+$' }
        name: { type: string, minLength: 1, maxLength: 255 }
        email: { type: string, format: email }
        status: { type: string, enum: [active, inactive, suspended] }
    CreateUserRequest:
      type: object
      required: [name, email]
      properties:
        name: { type: string, minLength: 1, maxLength: 255 }
        email: { type: string, format: email }
        role: { type: string, enum: [user, admin], default: user }

Pact Consumer Contract Test

// tests/contract/consumer/user-api.pact.js
const { PactV3, MatchersV3 } = require('@pact-foundation/pact');
const { like, eachLike, regex } = MatchersV3;

const provider = new PactV3({ consumer: 'frontend-app', provider: 'user-service' });

describe('User API Contract', () => {
  it('lists users', async () => {
    await provider
      .given('users exist')
      .uponReceiving('a request to list users')
      .withRequest({
        method: 'GET',
        path: '/users',
        query: { page: '1', limit: '20' },
        headers: { Authorization: regex(/^Bearer .+$/, 'Bearer token123') },
      })
      .willRespondWith({
        status: 200,
        body: {
          data: eachLike({ id: like('usr_abc'), name: like('Alice'), email: like('a@b.com') }),
          pagination: { page: like(1), limit: like(20), total: like(100) },
        },
      })
      .executeTest(async (mockServer) => {
        const res = await fetch(`${mockServer.url}/users?page=1&limit=20`, {
          headers: { Authorization: 'Bearer token123' },
        });
        expect(res.status).toBe(200);
        const body = await res.json();
        expect(body.data.length).toBeGreaterThan(0);
      });
  });

  it('rejects invalid create request', async () => {
    await provider
      .uponReceiving('an invalid create user request')
      .withRequest({
        method: 'POST', path: '/users',
        headers: { 'Content-Type': 'application/json', Authorization: 'Bearer token123' },
        body: { name: '' },
      })
      .willRespondWith({
        status: 400,
        body: {
          type: like('https://api.example.com/errors/validation'),
          title: like('Validation Error'),
          status: 400,
          errors: eachLike({ field: like('email'), message: like('Required') }),
        },
      })
      .executeTest(async (mockServer) => {
        const res = await fetch(`${mockServer.url}/users`, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json', Authorization: 'Bearer token123' },
          body: JSON.stringify({ name: '' }),
        });
        expect(res.status).toBe(400);
      });
  });
});

Spectral Linting Configuration

# .spectral.yaml
extends: spectral:oas
rules:
  operation-operationId:
    severity: error
  oas3-valid-schema-example:
    severity: error
  path-casing:
    severity: warn
    given: "$.paths[*]~"
    then:
      function: casing
      functionOptions: { type: kebab }

Provider Verification

const { Verifier } = require('@pact-foundation/pact');

it('satisfies consumer contracts', async () => {
  await new Verifier({
    providerBaseUrl: 'http://localhost:3000',
    pactUrls: ['./contracts/pact/frontend-app-user-service.json'],
    stateHandlers: {
      'users exist': async () => {
        await db.users.bulkCreate([
          { name: 'Alice', email: 'alice@example.com', status: 'active' },
        ]);
      },
    },
  }).verifyProvider();
});

Contract Generation Script

#!/bin/bash
npx @stoplight/spectral-cli lint openapi.yaml --fail-severity warn
npx swagger-cli validate openapi.yaml
npx openapi-to-postmanv2 -s openapi.yaml -o contracts/postman/collection.json
npx jest tests/contract/consumer/ --verbose
npx jest tests/contract/provider/ --verbose
echo "All contract checks passed"

Tons of Skills by Intent Solutions | jeremylongshore.com

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides tools and guidance for generating API contracts, OpenAPI specifications, and consumer-driven contract tests using Pact. No malicious patterns, obfuscation, or unauthorized data access were detected during the analysis.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 820dfc8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month
What it can do
Reads files Edits files Runs commands
version
1.26.0
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
[
  "api",
  "api-contracts"
]
All 6 allowed tools
ReadWriteEditGrepGlobBash(api:contract-*)
Other metadata
compatibility
Designed for Claude Code

README badge

README badge for jeremylongshore/tons-of-skills-marketplace/generating-api-contracts