Module: Tina4::Swagger

Defined in:
lib/tina4/swagger.rb

Class Method Summary collapse

Class Method Details

.add_schema(name, schema) ⇒ Object

Register a reusable component schema, referenceable via swagger_meta / [:response_schemas] or a raw $ref.



32
33
34
 
# File 'lib/tina4/swagger.rb', line 32

def add_schema(name, schema)
  @registered_schemas[name.to_s] = schema
end

.add_security_scheme(name, definition) ⇒ Object

Register a named OpenAPI security scheme (e.g. an oauth2 scheme with scopes, or a custom apiKey). Call at app bootstrap, before generate().

Tina4::Swagger.add_security_scheme("oauth2", {
  "type" => "oauth2",
  "flows" => { "clientCredentials" => {
    "tokenUrl" => "https://api.example.com/oauth/token",
    "scopes" => { "read:users" => "Read users", "write:users" => "Write users" }
  } }
})



26
27
28
 
# File 'lib/tina4/swagger.rb', line 26

def add_security_scheme(name, definition)
  @registered_schemes[name.to_s] = definition
end

.enabled? ⇒ Boolean

TINA4_SWAGGER_ENABLED — defaults to TINA4_DEBUG. Wired into RackApp’s /swagger serving (v3.13.40), so it genuinely gates whether the docs are served — it was dead code before.

Returns:

  • (Boolean) 


77
78
79
80
81
82
83
 
# File 'lib/tina4/swagger.rb', line 77

def enabled?
  explicit = ENV["TINA4_SWAGGER_ENABLED"]
  if explicit && !explicit.empty?
    return %w[true 1 yes on].include?(explicit.to_s.strip.downcase)
  end
  %w[true 1 yes on].include?(ENV.fetch("TINA4_DEBUG", "").to_s.strip.downcase)
end

.generate(routes = []) ⇒ Object 



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/tina4/swagger.rb', line 42

def generate(routes = [])
  spec = base_spec
  route_list = routes.empty? ? Tina4::Router.routes : routes
  # Accumulators shared across routes: ORM models referenced
  # (-> components.schemas), registered custom-schema names referenced
  # by routes, tags used (-> top-level tags[]), seen operationIds
  # (de-dup — OpenAPI requires them unique).
  ctx = { models: {}, ref_schemas: [], used_tags: [], seen_ids: [],
          schemes: spec["components"]["securitySchemes"] }
  route_list.each do |route|
    next unless included?(route.path)

    add_route_to_spec(spec, route, ctx)
  end

  unless ctx[:models].empty? && ctx[:ref_schemas].empty?
    spec["components"]["schemas"] ||= {}
    ctx[:models].each do |name, klass|
      spec["components"]["schemas"][name] = model_schema(klass)
    end
    ctx[:ref_schemas].each do |name|
      next unless @registered_schemas.key?(name)
      next if spec["components"]["schemas"].key?(name)

      spec["components"]["schemas"][name] = @registered_schemas[name]
    end
  end
  spec["tags"] = ctx[:used_tags].map { |t| { "name" => t } } unless ctx[:used_tags].empty?

  spec
end

.reset_registry ⇒ Object

Clear the security-scheme and schema registries (test helper).



37
38
39
40
 
# File 'lib/tina4/swagger.rb', line 37

def reset_registry
  @registered_schemes = {}
  @registered_schemas = {}
end