Class: JekyllOpenAPI::SchemaRenderer::HTML

Inherits:
Object
  • Object
show all
Defined in:
lib/jekyll_openapi/schema_renderer/html.rb

Overview

Renders a JSON-Schema as semantic, linkable HTML.

Unlike the TypeScript/XML renderers — which always follow $refs and inline everything — this renderer works in link mode: a reference to a named component schema becomes an anchor to that schema's definition (#schema-<name>) instead of being expanded. Anonymous inline schemas are rendered structurally. That keeps operation bodies compact, cross-links reused types, and makes recursion terminate for free (a link is never followed).

Markup is semantic and class-annotated (<dl>/<ul>/<div>, never tables); all styling is left to the consumer. Every class is oapi- prefixed. Emitted text is HTML-escaped.

Descriptions are plain-escaped by default. Pass a markdown: callable (text -> html) to render them as markdown instead — the core library has no markdown engine of its own, so the caller supplies one (the Jekyll filter wires in the site's converter; see Filters#oapi_html_schema).

Constant Summary collapse

ANCHOR_PREFIX =

Fragment prefix for a named schema, e.g. "schema-Pet". A Models section anchors each definition with the matching id (see oapi_schema_anchor).

"schema-"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(logger: JekyllOpenAPI.logger, markdown: nil) ⇒ HTML

Returns a new instance of HTML.

Parameters:

  • markdown (#call, nil) (defaults to: nil) —

    a text -> html converter for descriptions; when nil, descriptions are HTML-escaped plain text



36
37
38
39
 
# File 'lib/jekyll_openapi/schema_renderer/html.rb', line 36

def initialize(logger: JekyllOpenAPI.logger, markdown: nil)
  @logger = logger
  @markdown = markdown
end

Class Method Details

.anchor(name) ⇒ Object 



30
31
32
 
# File 'lib/jekyll_openapi/schema_renderer/html.rb', line 30

def self.anchor(name)
  "#{ANCHOR_PREFIX}#{name}"
end

.render(schema, logger: JekyllOpenAPI.logger, markdown: nil) ⇒ Object 



41
42
43
 
# File 'lib/jekyll_openapi/schema_renderer/html.rb', line 41

def self.render(schema, logger: JekyllOpenAPI.logger, markdown: nil)
  new(logger: logger, markdown: markdown).render(schema)
end

Instance Method Details

#render(input) ⇒ String

Returns HTML.

Parameters:

Returns:

  • (String) —

    HTML



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/jekyll_openapi/schema_renderer/html.rb', line 47

def render(input)
  schema = Schema.wrap(input)

  if schema.named_reference?
    # Link, don't follow. Any use-site (sibling) description still shows.
    return annotate(link(schema), schema.override_description)
  end
  if schema.reference?
    # External/unnamed ref: surface the pointer, don't fake a type.
    return ref_code(schema)
  end
  unless schema.mapping?
    @logger.warn("not a valid schema object: #{schema.raw.inspect}")
    return ""
  end

  html = base(schema)
  return "" if html.nil?
  annotate(html, schema.description)
end