Swagger JSON to Markdown

Obsidian plugin to convert swagger.json or openapi.json files into static Swagger-style Markdown.

The goal is to generate API documentation that feels close to Swagger UI, but works well inside Obsidian notes and PDF exports. The plugin does not try to reproduce interactive Swagger UI controls such as Try it out, editable fields, or Execute buttons, because those controls do not provide value in static Markdown or PDF output.

Features

• Converts Swagger 2.0 and OpenAPI 3.x JSON files to Markdown.
• Adds a context menu action to .json files in your vault.
• Adds a command to convert the active JSON file.
• Provides an options modal before generating the Markdown file.
• Generates complete documentation with full mode.
• Generates reusable fragments with fragment mode.
• Groups operations by tags.
• Filters fragment output by tag, operationId, HTTP method, and path.
• Uses real Markdown headings for Obsidian outline support and PDF bookmarks.
• Can disable Markdown headings and use HTML title blocks instead.
• Generates sections for API information, servers, endpoints, parameters, request bodies, responses, examples, and schemas.
• Keeps controlled HTML blocks with api-* classes so the bundled plugin CSS can render a Swagger-like layout.
• Sanitizes rich HTML found in OpenAPI description fields, including headings, tables, lists, code, tt, links, and line breaks.
• Converts description headings such as <h2> into plugin-styled heading blocks so they render consistently in Obsidian and PDF exports.
• Extracts embedded HTML or Markdown tables from schema property descriptions and renders them as full-width blocks below the schema table.
• Renders named examples from request bodies, responses, and parameters.
• Renders details for every response status code, not only the first one.
• Emits examples as fenced Markdown code blocks such as json, xml, or text.
• Resolves internal $ref values, detects recursive schema references, and reports warnings for unresolved internal, external, or remote references.

Installation

For manual installation in a vault, copy these files:

main.js
manifest.json
styles.css

into:

VaultFolder/.obsidian/plugins/swaggerjson-to-markdown/

Then enable the plugin in Obsidian under Settings -> Community plugins.

Install or Update a Local Build

To test changes from the source code, run these commands from the project folder:

npm install
npm run build

Close Obsidian, then copy the newly built main.js, together with manifest.json and styles.css, into the vault plugin folder shown above. Replace the existing files and reopen Obsidian. If testing on another device, transfer the files from this local build rather than downloading an older release.

Regenerate the Markdown after updating: previously generated notes do not update automatically.

Basic Usage

1. Right-click a .json file in Obsidian.
2. Select Convert Swagger/OpenAPI to Markdown.
3. Choose the generation mode and filters in the modal.
4. Click Convert.

You can also open a JSON file and run the command:

Convert active JSON to Swagger-style Markdown

The generated Markdown file is created next to the JSON file by default, unless you set an output folder in the modal or plugin settings.

Generation Modes

Full Mode

full mode generates complete API documentation. It includes:

• Obsidian frontmatter.
• Main API title.
• General API information.
• Server definitions.
• All operations grouped by tags.
• Global schemas.

When full mode is selected, the modal automatically fixes all filters to All and disables tag, operation, operation ID, method, and path controls. This is intentional: full mode means the whole API document.

The generated note includes:

---
cssclasses:
  - swagger-api-doc
  - swagger-api-full
---

Fragment Mode

fragment mode generates a reusable piece of documentation. It is useful when you want to embed a specific tag or operation inside a larger hand-written note.

Fragments can be filtered by:

• tag
• operationId
• HTTP method
• path

The generated fragment includes:

---
cssclasses:
  - swagger-api-doc
  - swagger-api-fragment
---

If you embed a generated fragment in another note with Obsidian embeds:

![[docs/generated/fragments/add-pet.md]]

the parent note should also include:

---
cssclasses:
  - swagger-api-doc
---

This ensures the bundled plugin CSS applies correctly to the embedded content.

Modal Options

• Mode: choose Full or Fragment.
• Tag: limits fragment output to operations with the selected tag.
• Operation: selects one specific operation from the current tag selection.
• Manual operation ID: filters by a specific operationId.
• Manual method and path: filters endpoints that do not have an operationId.
• Markdown headings: uses real Markdown headings, recommended for Obsidian outlines and PDF bookmarks.
• Fragment heading offset: changes the base heading level for fragments, from 1 to 5.
• Output folder: custom destination folder inside the vault. Empty means next to the JSON file.
• Markdown file name: output file name.
• Overwrite if it exists: replaces an existing Markdown file instead of creating a numbered file name.
• Open when finished: opens the generated note after conversion.

The method and path controls are dynamic. Methods only show values available for the current tag selection, and paths only show values available for the selected method.

Generated Content

For each operation, the output includes static documentation equivalent to the useful reading parts of Swagger UI:

• Summary and description.
• HTTP method and path.
• Parameters, including declared example and examples.
• Request body description, schema, and named examples.
• Response summary table.
• Details for each response status code.
• Response content types.
• Named response examples.
• Response model/schema.
• Global schemas in full mode.

For recursive schemas, the generator avoids infinite expansion. If a property points back to a schema already in the current reference branch, it is rendered as a schema link with Recursive reference. in the description cell.

Interactive Swagger UI controls are intentionally not generated:

• Try it out
• editable inputs
• Execute buttons
• interactive selectors

Examples and XML/JSON Code

Examples are rendered as fenced Markdown code blocks:

```xml
<env:Header>
  <ns3:Action>...</ns3:Action>
</env:Header>
```

This prevents XML examples from appearing as escaped text such as:

<env:Header>

In Obsidian and PDF exports, XML/JSON examples remain readable as code.

Rich Text Descriptions

OpenAPI descriptions sometimes contain HTML. The plugin sanitizes this HTML and keeps useful content such as:

• structural headings
• paragraphs
• line breaks
• lists
• tables
• code and tt
• safe http, https, and mailto links
• colspan and rowspan in tables

Unsupported visual wrappers and unsafe tags are removed while preserving useful text. Tags such as <h1> through <h6> are transformed into controlled api-rich-heading blocks instead of being escaped into visible text.

Description tables receive the api-description-table class. The bundled CSS keeps them PDF-friendly with fixed layout, full width, wrapping, smaller print sizing, and column widths that handle both five-column and six-column description tables. The layout avoids horizontal scrolling because generated documents are intended to work as static PDF exports.

When a schema property description contains an embedded table, the table is extracted out of the main properties table. The property row keeps a short description such as Status code. See table below., and the extracted table is rendered below the schema as its own block. This avoids rendering a table inside another table cell.

CSS in Obsidian

The Swagger-style CSS is bundled in the plugin styles.css file. You do not need to manually install a separate CSS snippet.

Generated notes include the required frontmatter:

---
cssclasses:
  - swagger-api-doc
  - swagger-api-full
---

Fragments use:

---
cssclasses:
  - swagger-api-doc
  - swagger-api-fragment
---

The styles are visible in Reading View and in rendered Markdown views. The final appearance can still vary depending on your active Obsidian theme.

PDF Export

For reliable PDF bookmarks, generate a document in full mode and export the generated Markdown file directly.

Recommended workflow:

1. Generate a full document.
2. Open the generated .md file directly in Obsidian.
3. Keep Markdown headings enabled.
4. Export the generated file.

For formal PDFs with bookmarks, the Obsidian plugin Better Export PDF is recommended. Obsidian's native PDF export may fail to create reliable bookmarks for complex documents that mix Markdown, HTML blocks, large tables, code blocks, and embedded fragments.

Avoid exporting a parent note that only embeds the generated full document:

![[docs/generated/api-full.md]]

Fragments are useful for manual documentation, but direct export of a full generated file is more reliable for final PDFs.

Recommended Vault Structure

my-vault/
  docs/
    openapi/
      swagger.json
    generated/
      api-full.md
      fragments/
        add-pet.md

One practical workflow is:

• Keep source OpenAPI JSON files under docs/openapi/.
• Generate full documentation into docs/generated/.
• Generate operation fragments into docs/generated/fragments/.
• Embed fragments in hand-written documentation notes when needed.

Errors and Warnings

When Markdown generation fails, Obsidian shows a short notice and opens an error modal with the full details.

Errors can happen when:

• the selected file is not valid JSON;
• the document is missing openapi or swagger;
• the document is missing the required info object;
• the document is missing a valid paths object;
• no operations are found under paths;
• the selected filters do not match any operation;
• the output file cannot be created or overwritten.

Warnings do not stop generation. They are reported in the Obsidian developer console and the completion notice shows the warning count. Typical warnings include:

• unresolved internal $ref;
• external file $ref;
• remote URL $ref;
• unexpected Swagger/OpenAPI version values;
• schema details that cannot be fully represented in the documentation tables;
• authentication requirements or security schemes that are not rendered.

A warning such as Schema at ... contains information not fully represented by tables; its JSON definition is preserved in the documentation. means the generator retains the schema definition in a JSON block rather than relying only on a simplified table. This can occur with enums, validation constraints, additionalProperties, or composed schemas.

Schema warnings are conservative: a property and its containing schemas can each produce a warning. A high warning count does not mean the same number of conversion failures. Review the generated Schema definition blocks for details; generated examples are representative values, not a guarantee that every schema constraint is satisfied.

Recursive internal $ref values are not warnings. They are expected in some OpenAPI documents and are rendered as finite links back to the referenced schema.

Known Limitations

• OpenAPI 3.0 nullable: true and OpenAPI 3.1 type arrays are supported. Nullable types are shown explicitly, for example string | null.
• Tables are not a complete JSON Schema representation. Additional constraints, composition branches, enums, and complex nested definitions are preserved in expandable Schema definition JSON blocks, with warnings when a table is incomplete. Generated examples are representative values, not a full JSON Schema validation result.
• Authentication requirements and security schemes are not rendered. Their presence produces a warning; consult the original specification.
• Named JSON Schema anchors and advanced reference scopes are not resolved; unresolved references produce warnings.
• External file $ref values are not resolved.
• Remote URL $ref values are not resolved.
• Automatic XML generation is limited; declared XML examples are preserved and rendered as code.
• Extremely complex schemas may require manual review.
• The visual result depends on the active Obsidian theme.
• PDF bookmark quality depends on the exporter; Better Export PDF is recommended for formal exports.
• Input support is JSON-focused. YAML OpenAPI files are not converted by this plugin.

Troubleshooting

Conversion Fails with n.startsWith is not a function

An older build could fail while generating examples for OpenAPI 3.1 type arrays such as "type": ["string", "null"]. The current source handles these declarations without treating the array as a string.

Build the current source with npm run build, close Obsidian, replace main.js in the vault plugin folder, and reopen Obsidian. Replacing only the source files or reopening an existing generated note does not update the installed plugin.

Styles Do Not Appear

Check that:

• the plugin is enabled;
• the generated note contains cssclasses: swagger-api-doc;
• you are viewing the note in Reading View or rendered Markdown mode;
• the parent note also has cssclasses: swagger-api-doc when embedding fragments.

PDF Bookmarks Are Missing

Use Better Export PDF and check that:

• you generated a full document;
• Markdown headings was enabled;
• you are exporting the generated file directly;
• you are not exporting only a parent note that embeds the generated file.

XML Examples Show < and >

The current generator emits examples as fenced code blocks, so XML should render as code rather than escaped HTML. Regenerate the document and check that the source example is declared as an OpenAPI example.

HTML Tags Appear as Text

Regenerate the Markdown file after updating the plugin. Older generated notes may already contain escaped HTML from a previous plugin version, such as visible <div> or <h2> text.

In newly generated files, rich description headings are emitted as api-rich-heading blocks and should render in Reading View or rendered Markdown mode. If tags still appear as text, check that:

• the latest main.js was copied into the vault plugin folder;
• the generated note was recreated, not only reopened;
• you are viewing the note in Reading View or rendered Markdown mode.

Description Tables Look Too Narrow

Copy the latest styles.css into the vault plugin folder and reload Obsidian. The table layout is controlled by CSS, especially for large description tables intended for PDF export.

There Are Unresolved $ref Warnings

Check that the referenced schema, parameter, response, or component exists in the same JSON document. If your OpenAPI file uses external references, bundle it into a single JSON file before running the plugin.

Development

Install dependencies:

npm install

Start the development build:

npm run dev

Create a production build:

npm run build

Run lint:

npm run lint

Run the regression suite:

npm test

The suite includes a synthetic SpringDoc OpenAPI 3.1 fixture. To additionally test the original local 36-operation, 47-schema regression document without committing its private metadata, set OPENAPI_REGRESSION_FILE to its path before running the tests. The optional test checks every operation, response status, and top-level request/response model property.

Plugin workflow tests use an in-memory Obsidian API mock. After building, set PLUGIN_REGRESSION_BUNDLE to ./main.js to run those checks against the actual production bundle instead of an in-memory source build. UI appearance and behavior in a real vault still require manual testing.

Changelog

1.1.4

Fixed

• Fixed startsWith is not a function during example generation for OpenAPI 3.1 type arrays, including nullable declarations such as "type": ["string", "null"].
• Unified schema type handling across tables and generated examples, including OpenAPI 3.0 nullable: true, arrays, maps, boolean schemas, and schemas without an explicit type.
• Preserved explicit null examples and defaults, parent properties and required fields in flattened object allOf schemas, and original definitions for compositions that cannot be safely flattened.
• Corrected internal $ref decoding for JSON Pointer escapes and URI encoding, with controlled errors for malformed references.
• Removed the runtime PostCSS dependency from the plugin bundle by stubbing its unused style parser; HTML style attribute parsing remains disabled.
• Removed complete and orphan HTML comment delimiters from rich descriptions before rendering.

Added

• Contextual validation errors for malformed schema declarations and metadata containers instead of raw JavaScript type errors.
• Expandable Schema definition JSON blocks for schema details not fully represented by tables, with explicit warnings about rendering limitations.
• Warnings when authentication definitions are not rendered or a representative example cannot be generated safely for certain advanced constraints.
• Regression coverage for SpringDoc OpenAPI 3.1 documents, nullable types, schema composition, references, and the plugin's file creation workflow, including optional checks against the production bundle.
• Local build installation instructions and guidance for interpreting schema warnings.

Credits

Based on the functionality from Krontur/swaggerjson_to_markdown.

Author: Oscar Gonzalez Tur

• Website: https://oscartur.dev/
• Support the project: https://buymeacoffee.com/krontur

License

MIT.