Class: SpecForge::Documentation::OpenAPI::V30::Operation

Inherits:
Object
  • Object
show all
Defined in:
lib/spec_forge/documentation/openapi/v3_0/operation.rb

Overview

Represents an OpenAPI 3.0 Operation object

Handles the complete definition of API operations including parameters, request bodies, responses, and security requirements for OpenAPI specs.

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(document) ⇒ Operation

Creates a new Operation from a document

Parameters:

  • document (Object) —

    The document containing operation data



28
29
30
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 28

def initialize(document)
  @document = document
end

Instance Attribute Details

#document ⇒ Object (readonly)

The document object containing structured API data

Returns:

  • (Object) —

    The document with endpoint information



21
22
23
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 21

def document
  @document
end

Instance Method Details

#description ⇒ String

Returns detailed description of the operation

Returns:

  • (String) —

    Detailed operation description



82
83
84
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 82

def description
  ""
end

#id ⇒ String Also known as: operationId

Returns the operation's unique identifier

Returns:

  • (String) —

    The operation ID



61
62
63
64
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 61

def id
  # The object ID is added to make every ID unique
  document.id + object_id.to_s
end

#parameters ⇒ Array

Returns parameter definitions for the operation

Transforms document parameters into OpenAPI parameter objects with proper schema types and location information.

Returns:

  • (Array) —

    Array of parameter objects



114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 114

def parameters
  document.parameters.values.map do |parameter|
    schema = Schema.new(type: parameter.type).to_h

    {
      schema:,
      name: parameter.name,
      in: parameter.location,
      required: parameter.location == "path" || false
    }
  end
end

#request_body ⇒ Hash? Also known as: requestBody

Returns request body definition for the operation

Groups requests by content type and creates proper OpenAPI request body object with examples and schemas.

Returns:

  • (Hash, nil) —

    Request body object



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 135

def request_body
  requests = document.requests
  return if requests.blank?

  requests = requests.group_by(&:content_type)

  content =
    requests.transform_values do |grouped_requests|
      media_type_from_requests(grouped_requests)
    end

  {
    description: "",
    content:
  }
end

#responses ⇒ Hash

Returns response definitions for the operation

Groups responses by status code and transforms them into OpenAPI response objects with proper formatting.

Returns:

  • (Hash) —

    Hash mapping status codes to response objects



162
163
164
165
166
167
168
169
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 162

def responses
  document.responses
    .group_by(&:status)
    .transform_values! do |responses|
      response = responses.first
      Response.new(response).to_h
    end
end

#security ⇒ Array

Returns security requirements for the operation

Returns:

  • (Array) —

    Array of security requirement objects



91
92
93
94
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 91

def security
  # User defined
  []
end

#summary ⇒ String?

Returns a human-readable summary of the operation

Returns:

  • (String, nil) —

    Brief operation summary



73
74
75
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 73

def summary
  document.summary
end

#tags ⇒ Array

Returns tags for categorizing the operation

Returns:

  • (Array) —

    Array of tag names



101
102
103
104
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 101

def tags
  # User defined
  []
end

#to_h ⇒ Hash

Converts the operation to an OpenAPI-compliant hash

Builds the complete operation object with all required and optional fields properly formatted for OpenAPI specification.

Returns:

  • (Hash) —

    OpenAPI-formatted operation object



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/spec_forge/documentation/openapi/v3_0/operation.rb', line 40

def to_h
  {
    # Required
    responses:,
    security:
  }.compact_merge(
    # All optional
    tags:,
    summary:,
    description:,
    operationId:,
    parameters:,
    requestBody:
  )
end