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.

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. The modal includes a Copy details button so the error can be copied into an issue, chat, or debugging note.

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.

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

• 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

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

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.