jekyll-openapi

A (mostly) spec-compliant OpenAPI 3.1 toolkit for Liquid-based static site generators (Jekyll in particular), with partial OpenAPI 3.2 support (see OpenAPI 3.2 support).

It deliberately does not render HTML. The gem provides:

• a navigable object model over a parsed OpenAPI document — dereferencing, tag and operation enumeration, parameter merging;
• schema-to-text renderers (TypeScript-like and simplified XML) exposed as opt-in Liquid filters;

…and your site provides the templates. See examples/ for complete, copy-paste-able templates.

The gem works as a plain Ruby library too — without Jekyll or Liquid. That usage, the object model, and the renderer API are documented in examples/ruby/README.md.

Add the gem to your Gemfile and list it as a plugin — nothing else to do, the filters register themselves and warnings are routed to Jekyll's logger:

# Gemfile
group :plugins do
  gem "jekyll-openapi"
end

# _config.yml
plugins:
  - jekyll-openapi

Four steps take you from a spec file to a rendered reference page.

1. Enable the plugin as shown above (Gemfile + plugins: entry). No _plugins/ file is needed.

2. Drop your spec into _data/ so Jekyll parses it into site.data:

_data/openapi.yml     # YAML or JSON; becomes site.data.openapi

3. Write a page that walks the tags and operations with the filters:

---
title: API Reference
---
{% assign api = site.data.openapi %}

<h1>{{ api.info.title }}</h1>

{% assign tags = api | oapi_tags %}
{% for tag in tags %}
  <h2>{{ tag.name }}</h2>
  {{ tag.description | markdownify }}

  {% assign ops = api | oapi_operations: tag.name %}
  {% for op in ops %}
    <h3>{{ op.method | upcase }} {{ op.path }}</h3>
    {{ op.operation.description | markdownify }}
  {% endfor %}
{% endfor %}

4. Build (bundle exec jekyll serve) and you have a page listing every operation, grouped by tag. That's a complete, working integration.

oapi_operations already does the tedious parts for you: it skips non-operation path-item keys, handles x- extension methods and OpenAPI 3.2 additionalOperations, filters by tag, and merges path-level parameters into each operation.

Each op in the loop is a plain Hash you can traverse further:

The walkthrough above is intentionally bare. For a production-quality page — tag index/navigation, parameter tables, request/response bodies with rendered schemas — start from the complete examples and restyle them:

• examples/jekyll/api-doc.html — a full API reference page: tag cloud, operations grouped by tag, path/query parameter tables, request and response schemas.
• examples/jekyll/_includes/oapi/schema.html — a reusable include that picks the XML or TypeScript renderer based on the content type.

Registered automatically in Jekyll. (In a plain Liquid setup you register them yourself — see examples/ruby/README.md.)

The text schema filters turn a JSON-Schema into readable text, e.g. {{ content.schema | oapi_schema }} produces:

{
  name: "string"
  age?: integer
}

oapi_html_schema instead emits semantic, class-annotated HTML (<dl>/<ul>, never tables) in which a $ref to a named component schema renders as a link to #schema-<name> rather than being inlined — so operation bodies stay compact, reused types are cross-linked, and recursive schemas terminate. Descriptions are rendered as markdown when run inside Jekyll (it reuses the site's configured converter) and as escaped plain text otherwise. Pair it with oapi_schemas + oapi_schema_anchor to emit a matching "Models" section; see examples/jekyll/_includes/oapi/models.html and schema.html (which picks a renderer by content type), styled by _sass/oapi-schema.scss.

The library never raises on malformed input: it warns through JekyllOpenAPI.logger (in Jekyll, routed to Jekyll's own logger) and degrades gracefully — unresolvable and external $refs are left in place and warn only when followed; recursive schemas terminate (rendered as a link, or their name in the text renderers); invalid schemas render as "". Your build never breaks on a bad spec.

Partial. Because the model hands templates plain hashes, most new 3.2 fields flow through untouched and are usable today; "supported" below means the library actively understands the feature, "passthrough" means the raw data reaches your template but no helper interprets it.

Supported:

• additionalOperations — enumerated by oapi_operations like any other operation, with path-level parameters merged; method is the lowercased method name, raw_method the literal key ("PROPFIND"). Gives webDAV-style APIs first-class treatment (previously only reachable via x- methods).
• The query HTTP method — recognized as a first-class path-item key.
• Tag summary — passes through oapi_tags (tested); use it as a short display name where description is prose.
• in: querystring parameters — grouped under their own "querystring" key by oapi_parameters / grouped_parameters (the parameter is content-based: render its media-type schema, not a name/value pair). An operation-level querystring parameter overrides a path-level one regardless of name, and mixing it with in: query parameters warns (the spec forbids it) but keeps both.

Passthrough (data reaches templates, no helper logic):

• Tag parent / kind — the fields are readable, but oapi_operations and oapi_tags treat tags as a flat list: no hierarchy building, no filtering by kind.
• Response summary, Server name — readable on the raw objects.
• Security scheme additions (deviceAuthorization flow, oauth2MetadataUrl, deprecated) — readable via oapi_security_schemes.

Not supported (TODO):

• Streaming / sequential media types — itemSchema, itemEncoding and prefixEncoding are ignored by the schema renderers and oapi_examples.
• Example Object dataValue / serializedValue — oapi_examples only reads value.
• xml.nodeType — the XML renderer still keys off the 3.1 attribute / wrapped flags.
• $self and multi-document descriptions — consistent with the existing local-$refs-only policy.
• components.mediaTypes reuse — untested; generic local $ref resolution may already handle it, but no guarantees.

Intentional simplifications, in the spirit of "readable docs over exhaustive fidelity":

• Only local (#/...) references are resolved; external files/URLs are left as-is.
• The TypeScript renderer supports oneOf/anyOf (|), allOf (&), 3.1 type arrays (type: [string, "null"]), enums, additionalProperties, and infers object/array when type is omitted — but does not merge allOf members into a single object literal.
• The XML renderer honors xml.name, xml.prefix, xml.namespace, xml.attribute and xml.wrapped, and renders example values where provided.

rake test          # or: ruby -Ilib -Itest test/test_<name>.rb

Tests run against generic fixtures (test/fixtures/petstore.yml, a pristine OpenAPI 3.1 document, and test/fixtures/filestore.yml, a WebDAV-flavored OpenAPI 3.2 one); when the gem sources live inside the eCorpus_doc repository, an extra integration suite runs the whole pipeline over the real eCorpus API definition.