gems/gitlab-grape-openapi/README.md
[!WARNING] This gem is currently designed entirely for internal use at GitLab. This gem is not functional and not used in production.
Internal gem for generating OpenAPI 3.0 specifications from Grape API definitions.
Add to your Gemfile:
gem 'gitlab-grape-openapi', path: 'gems/gitlab-grape-openapi'
Configure the gem using the Gitlab::GrapeOpenapi.configure block, typically in an initializer:
Gitlab::GrapeOpenapi.configure do |config|
# Required: API metadata
config.info = Gitlab::GrapeOpenapi::Models::Info.new(
title: 'My API',
description: 'API description',
version: 'v1',
terms_of_service: 'https://example.com/terms'
)
# API path configuration
config.api_prefix = "api" # Default: "api"
config.api_version = "v1" # Default: "v1"
# Server definitions
config.servers = [
Gitlab::GrapeOpenapi::Models::Server.new(
url: 'https://{hostname}',
description: "Production API",
variables: {
hostname: Gitlab::GrapeOpenapi::Models::ServerVariable.new(
default: 'api.example.com',
description: 'API hostname'
)
}
)
]
# Security schemes
config.security_schemes = [
Gitlab::GrapeOpenapi::Models::SecurityScheme.new(
name: "bearerAuth",
type: "http",
scheme: "bearer"
)
]
# Exclude specific API classes from generation
config.excluded_api_classes = [
'API::Internal::Base',
'API::Internal::Admin'
]
# Override tag names for better display
config.tag_overrides = {
'Ci' => 'CI',
'Oauth' => 'OAuth'
}
# Map Grape route settings to OpenAPI extensions
config.annotations = {
lifecycle: 'x-gitlab-lifecycle'
}
end
| Option | Type | Default | Description |
|---|---|---|---|
info | Models::Info | nil | API metadata (title, description, version, terms of service) |
api_prefix | String | "api" | URL prefix for API routes |
api_version | String | "v1" | API version string |
servers | Array<Models::Server> | [] | Server definitions for the API |
security_schemes | Array<Models::SecurityScheme> | [] | Authentication/authorization schemes |
excluded_api_classes | Array<String> | [] | API class names to exclude from generation |
tag_overrides | Hash | {} | Map of tag names to their display overrides |
annotations | Hash | {} | Map of Grape route settings to OpenAPI extension names |
The annotations configuration maps Grape route settings to OpenAPI vendor extensions. For example:
config.annotations = {
lifecycle: 'x-gitlab-lifecycle'
}
When a Grape endpoint has:
```ruby
route_setting :lifecycle, 'mature'
The generated OpenAPI spec will include:
x-gitlab-lifecycle: mature
# Load all API and entity classes
Rails.application.eager_load!
api_classes = API::Base.descendants
entity_classes = Grape::Entity.descendants
# Generate the specification
spec = Gitlab::GrapeOpenapi.generate(
api_classes: api_classes,
entity_classes: entity_classes
)
# Output as JSON
File.write('openapi.json', JSON.pretty_generate(spec))
# Or as YAML
require 'yaml'
File.write('openapi.yaml', spec.to_yaml)
gitlab-org/gitlabStart a Rails console in your GDK:
cd ~/gdk/gitlab
rails console
Generate the OpenAPI specification:
Rails.application.eager_load!
api_classes = API::Base.descendants
entity_classes = Grape::Entity.descendants
spec = Gitlab::GrapeOpenapi.generate(api_classes: api_classes, entity_classes: entity_classes)
File.write(Rails.root.join('tmp', 'openapi.json'), JSON.pretty_generate(spec))
The spec will be saved to tmp/openapi.json in your GitLab directory.
The gem follows a converter-based architecture:
Generator
├── TagConverter - Extracts tags from API classes
├── EntityConverter - Converts Grape::Entity to OpenAPI schemas
├── PathConverter - Converts routes to OpenAPI paths
│ ├── OperationConverter - Converts individual endpoints
│ ├── ParameterConverter - Converts endpoint parameters
│ ├── ResponseConverter - Converts endpoint responses
│ └── RequestBodyConverter - Converts request bodies
└── TypeResolver - Maps Ruby/Grape types to OpenAPI types
cd gems/gitlab-grape-openapi
bundle install
bundle exec rspec
bundle exec rspec
bundle exec rubocop
This gem is part of the GitLab monorepo. Please follow the GitLab contribution guidelines.