LegközelebbKövetkező útmutató
Tervezési eszközök LLM-ügynökök számára
Műszaki
Műszaki ÚTMUTATÓ
OpenAPI documents describe HTTP operations, parameters, request bodies, responses, and security schemes in a machine-readable format.
Hallgassa meg ezt az útmutatótAI-narrált · ~3 min
Turning selected operations into LLM tools requires curating a safe surface, translating schemas, and keeping authorization and execution in application code.
OpenAPI (formerly Swagger) is a machine-readable format that describes a REST API's endpoints, parameters, request bodies and responses using version-specific Schema Objects for data shapes; OpenAPI 3.1 and later align these with JSON Schema, while earlier versions differ. Since most LLM tool-calling systems, including MCP and native function-calling APIs, already expect JSON-Schema-shaped parameter definitions, the endpoint and parameter portion of an OpenAPI document maps fairly directly onto a tool definition: the path and method become the tool's identity, the parameters and request body become its input schema, and the summary or description fields become the tool's description. Several open-source converters (such as openapi-to-mcp style generators, or lightweight scripts built on libraries like openapi-schema-validator) automate this mechanical mapping. The harder, non-mechanical part is curation: production OpenAPI specs frequently describe hundreds of endpoints, many overlapping or rarely used, and their descriptions are written for engineers integrating code, not for a model deciding whether to call something. Practitioners typically prune the spec down to the handful of endpoints a given use case needs, rewrite ambiguous parameter descriptions in plain language, add example values, and flag irreversible or sensitive actions explicitly, since OpenAPI has no native concept of 'this deletes data permanently.' A common misconception is that feeding an entire large OpenAPI file to a model as tools works out of the box; in practice, tool count and description clarity both strongly affect whether the model picks the right tool and fills in arguments correctly.
A logistics company runs its shipping API's OpenAPI file through a converter to generate a get_shipment_status tool, then manually rewrites the auto-generated description because the original was written for engineers, not for a model deciding when to call it.
A support team exposes only 6 of their 140 documented endpoints as tools, since including the full spec would overwhelm the model's context and increase the chance it picks the wrong endpoint.
A fintech startup generates a create_payment tool from its OpenAPI spec but adds a manual confirmation step in the tool description, since the spec alone does not convey that this action is irreversible.
A developer converting a weather API notices the OpenAPI spec marks a units parameter as optional with no example, so the model frequently omits it inconsistently, and adds an explicit default and example value to the generated tool schema.
OpenAPI schemas and function-calling interfaces evolve, and the latest OAS version may not match a service’s own document or a model endpoint’s supported schema. Keep the source document versioned, regenerate only curated operations, and run tests against the live contract before release. Human decisions remain necessary for tool exposure, authorization, confirmation, and user-facing descriptions; generation can assist mapping but cannot infer every business rule. Also retest permissions when user roles or API scopes change. Verify pagination, errors, and idempotency in execution.
Ingyenes hírlevél
Minden hétköznap reggel három ellenőrzött AI történet, egyszerű angol nyelven. Örökké ingyen, hirdetések nélkül.
Minden hétköznap egy e-mail. Egy kattintással lemondhat. Soha nem értékesítjük vagy osztjuk meg az Ön címét.
Teszteld magad
Azonnali visszajelzés minden válaszra, és megosztható tanúsítvány egy ellenőrizhető azonosítóval, miután sikeresen teljesít egy kurzust.
Támogassa az ingyenes AI oktatást. AI Understanding egy 501(c)(3) nonprofit – nincs hirdetés, nincs fizetőfal, soha. Tegyen adományt
OpenAPI documents describe HTTP operations, parameters, request bodies, responses, and security schemes in a machine-readable format. Turning selected operations into LLM tools requires curating a safe surface, translating schemas, and keeping authorization and execution in application code.
The conversion maps REST endpoint structure and parameters onto the tool schema format models expect.
Curating down to a relevant subset reduces the risk of the model selecting an unsuitable or overlapping endpoint.
OpenAPI documents an HTTP interface, but the application must add context-specific confirmation and authorization rules for sensitive side effects.
OpenAPI 3.1 adopted a Schema Object based on JSON Schema 2020-12; OpenAPI 3.0 uses a different, restricted schema dialect, so conversion must account for the source version.
A modellnek argumentumokat kell megadnia, nem titkokat. Az alkalmazáskódnak a jogosult felhasználótól vagy szolgáltatáskontextustól kell megszereznie a hitelesítőadatokat, és biztonságosan végrehajtania a hívást.
Tanulj tovább
További útmutatók készültek ehhez a témához
LegközelebbKövetkező útmutató
Tervezési eszközök LLM-ügynökök számára
Műszaki