Skip to content

openapi_3.md

Latest commit

 

History

History
113 lines (95 loc) · 3.59 KB

openapi_3.md

File metadata and controls

113 lines (95 loc) · 3.59 KB
Raw

OpenAPI 3.0/3.1 Support

Quick Start

# Swagger 2.0 (default, unchanged)
add_swagger_documentation

# OpenAPI 3.0
add_swagger_documentation(openapi_version: '3.0')

# OpenAPI 3.1
add_swagger_documentation(openapi_version: '3.1')

Configuration Options

add_swagger_documentation(
  openapi_version: '3.1',
  info: {
    title: 'My API',
    version: '1.0',
    description: 'API description',
    license: {
      name: 'MIT',
      url: 'https://opensource.org/licenses/MIT',
      identifier: 'MIT'  # OAS 3.1 only (SPDX)
    }
  },
  security_definitions: {
    bearer: { type: 'http', scheme: 'bearer' }
  },
  # OAS 3.1 specific
  json_schema_dialect: 'https://json-schema.org/draft/2020-12/schema',
  webhooks: {
    newUser: {
      post: {
        summary: 'New user webhook',
        requestBody: { ... },
        responses: { '200' => { description: 'OK' } }
      }
    }
  }
)

Key Differences from Swagger 2.0

Aspect Swagger 2.0 OpenAPI 3.x
Version swagger: '2.0' openapi: '3.0.3' / '3.1.0'
Body params in: body parameter requestBody object
Form params in: formData requestBody with content-type
File upload type: file type: string, format: binary
Schema refs #/definitions/X #/components/schemas/X
Host host, basePath, schemes servers: [{url: "..."}]
Security defs securityDefinitions components/securitySchemes
Param types inline type, format wrapped in schema

Nullable Fields

# Recommended syntax
params do
  optional :nickname, type: String, documentation: { nullable: true }
end

# Also supported (for backward compatibility with Swagger 2.0 code)
params do
  optional :nickname, type: String, documentation: { x: { nullable: true } }
end

Both syntaxes produce version-appropriate output:

Syntax Swagger 2.0 OAS 3.0 OAS 3.1
documentation: { nullable: true } x-nullable: true nullable: true type: ["string", "null"]
documentation: { x: { nullable: true } } x-nullable: true nullable: true type: ["string", "null"]

This means existing Swagger 2.0 code using x: { nullable: true } works seamlessly when switching to OAS 3.x.

Architecture

Grape Routes
     │
     ▼
┌─────────────────────────────┐
│  Builder::Spec              │
│  (lib/grape-swagger/openapi)│
└─────────────────────────────┘
     │
     ▼
┌─────────────────────────────┐
│  OpenAPI Model Layer        │
│  (Document, Schema, etc.)   │
└─────────────────────────────┘
     │
     ├──────────────┬──────────────┐
     ▼              ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│ Swagger2 │  │  OAS30   │  │  OAS31   │
│ Exporter │  │ Exporter │  │ Exporter │
└──────────┘  └──────────┘  └──────────┘

Backward Compatibility

  • Default unchanged: Without openapi_version, Swagger 2.0 is generated
  • All existing options work: Same configuration for both versions
  • Model parsers unchanged: grape-entity, representable, etc. work as before