oasviz - OpenAPI Specification Visualizer

oasviz is a Typst library designed for visualizing OpenAPI Specification (OAS) documents. It provides a suite of components to render API endpoints, data schemas, and server configurations in a structured and aesthetically pleasing format.

This library was significantly refactored and optimized with the assistance of the Gemini CLI Development Agent.

Design Philosophy

Style Inheritance: The library is built to be "style-neutral." It does not impose its own font sizes, internal padding, or block margins. Instead, it is designed to inherit these settings from the global set rules of the host document (e.g., lib.typ).
Swiss Minimalism: Follows a Swiss-inspired minimalist aesthetic, utilizing square shapes (radius: 0pt), clean borders, and a high-contrast layout.
Project Integration: Deeply integrated with the project's core utilities:
- ../pallete.typ: Uses the centralized palette for UI elements and semantic HTTP method colors.
- ../util/tabler.typ: Utilizes specialized table layouts for operation documentation.

Core Features

1. Localization (i18n)

The library uses a dedicated translate function supporting English and German. It employs a flat dot-notation key structure for clarity and maintainability. Recent updates have expanded the key set to ensure full localization of all UI elements, including captions and schema details.

Key Improvements:

Expanded Abbreviations: "Ex" is now "Example" (EN) / "Beispiel" (DE), and "Ref" is "Uses schema" (EN) / "Verwendet Schema" (DE).
Full Schema Localization: Terms like "Type", "Array of", and "any" are now fully translated.
Consistent Naming: All keys follow a strict dot-notation pattern (e.g., endpoints.uses-schema, common.example).

Example Keys:

translate("endpoints.title")
translate("servers.table.addr")
translate("common.example")

2. Semantic Method Badges

HTTP methods are visualized using flat, color-coded badges that prioritize readability while maintaining the minimalist design language.

3. Schema Rendering

Automatically renders complex JSON Schema definitions into clean, readable tables, complete with property types, descriptions, and examples.

Usage

The primary entry point is the render function, which accepts a Typst dictionary representing an OpenAPI document:

#import "oasviz/oasviz.typ": render
#let data = yaml("openapi.yaml")
#render(data)

2.5 KiB Raw Blame History