OpenAPI Specification

The industry standard for REST API documentation - and the key to schema-based API security.

What is OpenAPI?

The OpenAPI Specification (formerly Swagger) is a language-agnostic standard for describing REST APIs. It defines endpoints, parameters, request/response formats, and authentication in a machine-readable format (YAML or JSON).

OpenAPI 3.0 is developed by the OpenAPI Initiative under the Linux Foundation and is the de-facto standard for API documentation. Leading companies like Google, Microsoft, IBM, and Amazon use OpenAPI for their APIs.

OpenAPI as Security Contract

  • Allowlist approach: Only what is explicitly defined is allowed
  • Complete definition: Every aspect of the API is documented
  • Machine-readable: Automatic validation of every request
  • Bidirectional: Both requests and responses are validated

What OpenAPI Validates

Request Validation

  • Paths: Only defined endpoints allowed
  • HTTP Methods: GET, POST, PUT, DELETE per path
  • Parameters: Type, format, pattern validation
  • Request Body: JSON Schema validation
  • Content-Type: Allowed media types

Response Validation

  • Status Codes: Only defined codes allowed
  • Response Body: JSON Schema validation
  • Fields: Only defined properties
  • Formats: email, uri, date-time, etc.
  • Constraints: minLength, maxLength, etc.

OpenAPI Syntax Examples

1. Path and Method Definition

Define an endpoint with path parameters and HTTP method:

paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
            minimum: 1

2. Request Body Schema

Define the structure of a POST request body with validation constraints:

    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 255
                name:
                  type: string
                  minLength: 2
                  maxLength: 100
                  pattern: '^[a-zA-Z ]+$'
              additionalProperties: false

Security note: additionalProperties: false prevents injection of unexpected fields like isAdmin: true

3. Response Schema

Define what the API may return - Signando REST validates this bidirectionally:

      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  email:
                    type: string
                    format: email
                  name:
                    type: string
                  createdAt:
                    type: string
                    format: date-time
                additionalProperties: false
        '404':
          description: User not found

Security note: Response validation prevents data exfiltration - if a compromised backend tries to return passwordHash, Signando REST blocks it.

Secure Your API with OpenAPI

Learn how Signando REST uses your OpenAPI specification as a security contract.

Request Consultation