Guides / openapi spec

Comment publier une spécification OpenAPI pour les agents IA

Une spécification OpenAPI dit aux agents IA exactement ce que votre API peut faire. Voici comment en créer et en publier une.

Why OpenAPI matters for agents

An OpenAPI specification is the single most important file for AI agent integration. It tells agents exactly what endpoints exist, what parameters to send, what responses to expect, and how to authenticate.
Without an OpenAPI spec, an agent has to scrape your docs site and guess at your API contract. With one, it can generate type-safe API calls automatically.

Minimal spec template

Start with a minimal OpenAPI 3.0 spec and expand from there:

yaml

openapi: 3.0.3
info:
  title: Your API
  version: "1.0"
  description: |
    Brief description of what your API does.

servers:
  - url: https://api.your-domain.com/v1

paths:
  /items:
    get:
      summary: List items
      description: Returns a paginated list of items.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        "200":
          description: A list of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Item"
                  next_cursor:
                    type: string
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: string
          example: "item_abc123"
        name:
          type: string
          example: "Widget"
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string

  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - ApiKey: []

Where to host it

Publish your spec at a standard path. Serge checks these locations:
/openapi.json or /openapi.yaml (recommended)
/api/openapi.json
/.well-known/openapi.json
/swagger.json (legacy but still common)
The file should be publicly accessible without authentication. Reference it from your llms.txt file.

What makes a good spec

The Serge scanner checks several quality dimensions:
Schema completeness — Every endpoint should have typed request and response schemas, not just type: object
Error responses — Document 4xx and 5xx responses with schemas. Agents need to handle errors gracefully
Examples and descriptions — Add example values to properties and description to every endpoint. This helps agents understand intent, not just structure
Security schemes — Document how to authenticate. Without this, agents cannot make authenticated requests

Tools to help

Swagger Editor (editor.swagger.io) — Visual editor for OpenAPI specs
Redocly CLI — Lint and validate your spec: npx @redocly/cli lint openapi.yaml
Fern / Speakeasy — Generate specs from your code, or generate SDKs from your spec
Stoplight Studio — Visual API design tool with OpenAPI export

Vérifiez votre score

Après avoir implémenté ceci, scannez votre domaine pour vérifier que la vérification passe et voir comment votre score change.

Scanner votre domaine