DOCSEARCHbyAlgolia
Submit Docs

OpenAPI Specification (OAS)

repository·main·Indexed 12 days ago

https://github.com/oai/openapi-specification

A community-driven, language-agnostic standard for describing REST HTTP APIs using JSON or YAML. It enables automation for documentation, client/server code generation, and testing. The specification includes JSON Schema files for validation of versions 2.0 and 3.0.X, as well as guidelines for feature proposals and the use of elements like webhooks and callbacks.

Tokens
140.2K
Snippets
312
Records
540
Agent score
90%

What's inside OpenAPI Specification

  1. What is the OpenAPI Specification (OAS)?

    main

    The OpenAPI Specification (OAS) is a community-driven, programming language-agnostic standard for describing HTTP APIs. It provides a machine-readable interface description that allows both humans and computers to discover and understand a service's capabilities without needing access to source code or network traffic inspection.

    Key Characteristics:

    • Formats: API definitions are represented in YAML or JSON.
    • Scope: Primarily supports REST APIs.
    • Flexibility: Supports both design-first and code-first development processes.
    • Decoupling: Describing a service with OpenAPI does not require rewriting the API or owning the service.

    Common Use Cases:

    • Generating interactive documentation.
    • Automating code generation for clients and servers.
    • Automating test case generation.

  2. What is the Swagger 2.0 specification?

    main

    Swagger (formerly the Swagger RESTful API Documentation Specification) is a project used to describe and document RESTful APIs. The specification defines a set of files that describe an API's structure, which can be consumed by various tools:

    • Swagger-UI: To visually display and interact with the API.
    • Swagger-Codegen: To generate client libraries in multiple programming languages.
    • Testing Tools: Other utilities can use the specification files to automate API testing.

    Note that the keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in the specification follow RFC 2119.

  3. Understand the OpenAPI Specification (OAS) purpose

    main

    The OpenAPI Specification (OAS) provides a language-agnostic interface for HTTP APIs. It allows humans and machines to discover and understand service capabilities without source code access.

    An OpenAPI Description (OAD) can be used for:

    • Documentation generation: Displaying the API via tools.
    • Code generation: Creating servers and clients in various programming languages.
    • Testing: Automating API testing.
    • Interaction: Parsing and serializing HTTP messages to and from a data model.

  4. What is an OpenAPI Document

    main

    An OpenAPI Document is a self-contained or composite resource that describes an API or specific elements of an API. To be a valid OpenAPI document, it MUST contain at least one of the following fields:

    • paths
    • components
    • webhooks

    These documents allow humans and computers to discover and understand API capabilities without needing access to source code or network traffic inspection.

  6. What is an OpenAPI Description (OAD)?

    main

    An OpenAPI Description (OAD) is a formal description of an API's surface and its semantics. It consists of an entry document (which must be an OpenAPI Document) and any referenced documents.

    To be a valid OAD, the description MUST contain at least one of the following fields:

    • paths
    • components
    • webhooks

  7. What is an OpenAPI Overlay document?

    main

    An OpenAPI Overlay document is a separate specification used to apply a list of updates to a target OpenAPI document. Instead of modifying the original source, you create an Overlay document containing updates that use JMESPath queries to identify specific parts of the target document to modify, add to, or remove.

    This allows for scenarios like multi-language support (overriding descriptions), applying API-wide standards (adding common headers/parameters), or adding tool-specific metadata (SLA info, codegen hints) without polluting the core API definition.

    overlay: 1.0.0
info:
  title: My Overlay
  version: 1.0.0
extends: https://example.com/api.yaml
updates:
  - target: "$.paths['/user'].get"
    merge:
      summary: "Updated summary"

  8. Handle delimiters and percent-encoding in parameter values

    main

    When using RFC6570 expansion, delimiters (like the , used for style: "simple") are handled based on the allowReserved setting:

    • If allowReserved is false: Delimiters are automatically percent-encoded. Note that because RFC6570 doesn't specify how to parse variables back, you must split values by the delimiter before percent-decoding them.
    • If allowReserved is true: Both percent-encoding (before joining) and percent-decoding (after splitting) must be performed manually by the implementation.

    Warning: allowReserved: true does not allow characters that are illegal in URIs (like [, ], or #). It only allows reserved characters to be passed through expansion unchanged if they have a specific meaning in the target context.

  9. Avoid fragmentary parsing of OpenAPI content

    main

    When building or using tools to parse OpenAPI documents, avoid parsing referenced fragments in isolation. In version 3.1 and later, parsing fragments without the context of the containing document results in undefined behavior.

    Specifically, failing to account for keywords that change the base URI (like baseUri or url) can lead to security risks where references resolve to unintended URIs. While some older implementations support isolated fragment parsing, it is NOT RECOMMENDED for OpenAPI 3.1+.

  10. Understand Case Sensitivity and Behavior types

    main

    Case Sensitivity

    Most field names and values in the OpenAPI Specification are case-sensitive. Field names and values mapping to HTTP concepts follow standard HTTP case-sensitivity rules.

    Behavior Definitions

    • Undefined Behavior: Scenarios where outcomes might contradict the specification. Relying on these is NOT RECOMMENDED as they may not work across different tools or future versions.
    • Implementation-Defined Behavior: Scenarios where multiple compliant approaches exist. Authors are RECOMMENDED to avoid these to maximize interoperability. It is only safe to rely on these if you can guarantee all relevant tools support the same behavior.

  11. Use runtime expressions for Callback URLs

    main

    In OpenAPI 3.2.0, the key identifying a Path Item Object within a callback can be a runtime expression. These expressions are evaluated in the context of an HTTP request/response to dynamically determine the callback URL. You can access parts of the request (path, query, headers, body) or the response using specific syntax. For body access, use JSON Pointer RFC6901 syntax.

    Common Runtime Expressions:

    • $url: The full URL of the request.
    • $method: The HTTP method (e.g., POST).
    • $request.path.{name}: A specific path parameter value.
    • $request.query.{name}: A specific query parameter value.
    • $request.header.{name}: A specific header value.
    • $request.body#{/json/pointer}: A value from the request body using a JSON Pointer.
    • $response.header.{name}: A value from the response header.
    myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

  12. How sequential JSON media types work

    main

    Sequential JSON media types like application/json-seq, application/jsonl, or application/x-ndjson allow for streaming multiple JSON documents.

    • application/json-seq: Uses the unprintable Record Separator (0x1E) character to separate JSON documents.
    • application/jsonl / application/x-ndjson: Uses newlines to separate JSON documents.

    When modeling these in OpenAPI, you can use itemSchema to define the structure of the individual items within the stream.