liveBook · Manning

OpenAPI specification

As explained in AI Agents in Action

An OpenAPI specification is a machine-readable standard description of an HTTP API's endpoints, operations, parameters, and data structures.

An OpenAPI specification is a machine-readable description of an HTTP API. It can describe endpoints, operations, responses, and data schemas, giving an assistant a definition of the service it can call. section 3.3.1 section 3.3.2

A practical workflow uses the specification to connect an assistant to a service:

  • Create a FastAPI endpoint and retrieve its generated specification from the Swagger docs, in JSON or YAML. section 3.3.1
  • Paste the specification into the assistant’s custom action and add a servers entry containing the service URL. section 3.3.2
  • Test the action, and update its specification if the API changes. section 3.3.2

Daily tasks endpoint

A GET /tasks endpoint returns a list of Task objects. Its specification describes the successful JSON response as an array and defines each task’s id, description, and completed fields. section 3.3.1

Listing 3.12 OpenAPI specification for the task API
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
paths:
  /tasks:
    get:
      summary: Get Tasks
      description: Retrieve a list of daily tasks.
      operationId: get_tasks_tasks_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
                title: Response Get Tasks Tasks Get
components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: integer
          title: Id
        description:
          type: string
          title: Description
        completed:
          type: boolean
          title: Completed
      required:
        - id
        - description
        - completed
      title: Task

Inspect the generated OpenAPI 3.1.0 YAML for the task endpoint, including its path, response, and Task schema. section 3.3.1

How AI Agents in Action covers it

How deep it goes
Demonstrates a generated endpoint specification down to paths, response schemas, and data fields.
Examples
Uses a GET /tasks endpoint whose response contains task IDs, descriptions, and completion states.
What it assumes
Assumes a running service and external URL, while demonstrating specification generation from a FastAPI endpoint.
What you can do after
Apply it via GPT custom actions by configuring a service specification and testing the resulting connection.
How it connects
Links OpenAPI specifications with FastAPI services, Swagger docs, and assistant custom actions.

Also explained in

Compare how 14 books explain OpenAPI specification →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of AI Agents in Action. The section links point to the parts of the book it draws on.