Module: BetterAuth::OpenAPI

Defined in:
lib/better_auth/plugins/open_api.rb

Class Method Summary collapse

Class Method Details

.array_schema(items) ⇒ Object 



97
98
99
 
# File 'lib/better_auth/plugins/open_api.rb', line 97

def array_schema(items)
  {type: "array", items: items}
end

.default_error_responses ⇒ Object 



145
146
147
148
149
150
151
152
153
154
 
# File 'lib/better_auth/plugins/open_api.rb', line 145

def default_error_responses
  {
    "400" => error_response("Bad Request. Usually due to missing parameters, or invalid parameters.", required: true),
    "401" => error_response("Unauthorized. Due to missing or invalid authentication.", required: true),
    "403" => error_response("Forbidden. You do not have permission to access this resource or to perform this action."),
    "404" => error_response("Not Found. The requested resource was not found."),
    "429" => error_response("Too Many Requests. You have exceeded the rate limit. Try again later."),
    "500" => error_response("Internal Server Error. This is a problem with the server that you cannot fix.")
  }
end

.default_metadata(path, methods) ⇒ Object 



169
170
171
172
173
174
175
 
# File 'lib/better_auth/plugins/open_api.rb', line 169

def default_metadata(path, methods)
  method = Array(methods).reject { |value| value.to_s == "*" }.first.to_s.upcase
  {
    operationId: operation_id(path, method),
    description: "#{method} #{path}"
  }
end

.empty_request_body ⇒ Object 



118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/better_auth/plugins/open_api.rb', line 118

def empty_request_body
  {
    content: {
      "application/json" => {
        schema: {
          type: "object",
          properties: {}
        }
      }
    }
  }
end

.error_response(description, required: false) ⇒ Object 



156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/better_auth/plugins/open_api.rb', line 156

def error_response(description, required: false)
  schema = {
    type: "object",
    properties: {
      message: {
        type: "string"
      }
    }
  }
  schema[:required] = ["message"] if required
  json_response(description, schema)
end

.json_request_body(schema, required: true) ⇒ Object 



15
16
17
18
19
20
21
22
23
24
25
 
# File 'lib/better_auth/plugins/open_api.rb', line 15

def json_request_body(schema, required: true)
  request = {
    content: {
      "application/json" => {
        schema: schema
      }
    }
  }
  request[:required] = true if required
  request
end

.json_response(description, schema) ⇒ Object 



27
28
29
30
31
32
33
34
35
36
 
# File 'lib/better_auth/plugins/open_api.rb', line 27

def json_response(description, schema)
  {
    description: description,
    content: {
      "application/json" => {
        schema: schema
      }
    }
  }
end

.nullable(type) ⇒ Object 



101
102
103
104
 
# File 'lib/better_auth/plugins/open_api.rb', line 101

def nullable(type)
  types = Array(type)
  (types.include?("null") ? types : types + ["null"])
end

.object_schema(properties, required: []) ⇒ Object 



7
8
9
10
11
12
13
 
# File 'lib/better_auth/plugins/open_api.rb', line 7

def object_schema(properties, required: [])
  {
    type: "object",
    properties: properties,
    required: required
  }
end

.operation_id(path, method) ⇒ Object 



177
178
179
180
181
182
183
184
185
 
# File 'lib/better_auth/plugins/open_api.rb', line 177

def operation_id(path, method)
  parts = path.to_s.split("/").reject(&:empty?).map do |part|
    part.delete_prefix(":").gsub(/[^a-zA-Z0-9]+/, " ").split.map(&:capitalize).join
  end
  base = parts.join
  return method.downcase if base.empty?

  "#{method.to_s.downcase}#{base}"
end

.path_parameter(name, schema: {type: "string"}, description: nil) ⇒ Object 



112
113
114
115
116
 
# File 'lib/better_auth/plugins/open_api.rb', line 112

def path_parameter(name, schema: {type: "string"}, description: nil)
  parameter = {name: name, in: "path", required: true, schema: schema}
  parameter[:description] = description if description
  parameter
end

.query_parameter(name, required: false, schema: {type: "string"}, description: nil) ⇒ Object 



106
107
108
109
110
 
# File 'lib/better_auth/plugins/open_api.rb', line 106

def query_parameter(name, required: false, schema: {type: "string"}, description: nil)
  parameter = {name: name, in: "query", required: required, schema: schema}
  parameter[:description] = description if description
  parameter
end

.ref_schema(name, type: "object") ⇒ Object 



93
94
95
 
# File 'lib/better_auth/plugins/open_api.rb', line 93

def ref_schema(name, type: "object")
  {type: type, "$ref": "#/components/schemas/#{name}"}
end

.responses(responses = nil) ⇒ Object 



131
132
133
 
# File 'lib/better_auth/plugins/open_api.rb', line 131

def responses(responses = nil)
  {"200" => success_response}.merge(default_error_responses).merge(responses || {})
end

.session_response_schema(description:, nullable_url: false) ⇒ Object 



38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/better_auth/plugins/open_api.rb', line 38

def session_response_schema(description:, nullable_url: false)
  object_schema(
    {
      redirect: {type: "boolean", enum: [false]},
      token: {type: "string", description: "Session token"},
      url: nullable_url ? {type: "string", nullable: true} : {type: "string"},
      user: {type: "object", "$ref": "#/components/schemas/User"}
    },
    required: ["redirect", "token", "user"]
  ).merge(description: description)
end

.session_response_schema_pair ⇒ Object 



65
66
67
68
69
70
71
72
73
 
# File 'lib/better_auth/plugins/open_api.rb', line 65

def session_response_schema_pair
  object_schema(
    {
      session: {type: "object", "$ref": "#/components/schemas/Session"},
      user: {type: "object", "$ref": "#/components/schemas/User"}
    },
    required: ["session", "user"]
  )
end

.status_response_schema(extra_properties = {}, required: ["status"]) ⇒ Object 



75
76
77
78
79
80
81
82
 
# File 'lib/better_auth/plugins/open_api.rb', line 75

def status_response_schema(extra_properties = {}, required: ["status"])
  object_schema(
    {
      status: {type: "boolean"}
    }.merge(extra_properties),
    required: required
  )
end

.success_response ⇒ Object 



135
136
137
138
139
140
141
142
143
 
# File 'lib/better_auth/plugins/open_api.rb', line 135

def success_response
  json_response(
    "Success",
    {
      type: "object",
      properties: {}
    }
  )
end

.success_response_schema ⇒ Object 



84
85
86
87
88
89
90
91
 
# File 'lib/better_auth/plugins/open_api.rb', line 84

def success_response_schema
  object_schema(
    {
      success: {type: "boolean"}
    },
    required: ["success"]
  )
end

.user_response_schema ⇒ Object 



50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/better_auth/plugins/open_api.rb', line 50

def user_response_schema
  object_schema(
    {
      id: {type: "string", description: "The unique identifier of the user"},
      email: {type: "string", format: "email", description: "The email address of the user"},
      name: {type: "string", description: "The name of the user"},
      image: {type: "string", format: "uri", nullable: true, description: "The profile image URL of the user"},
      emailVerified: {type: "boolean", description: "Whether the email has been verified"},
      createdAt: {type: "string", format: "date-time", description: "When the user was created"},
      updatedAt: {type: "string", format: "date-time", description: "When the user was last updated"}
    },
    required: ["id", "email", "name", "emailVerified", "createdAt", "updatedAt"]
  )
end