How to embed Docson in a website without a server?

You can use the offline usage tutorial from the README, which involves serving files locally, but it requires manual setup to avoid CORS issues since Docson runs client-side. Alternatively, embed it via script tags if schemas are hosted on the same origin.

Docson vs Redoc for JSON schema documentation?

Docson focuses on interactive, browser-based visualization for JSON Schema v4, while Redoc supports newer OpenAPI versions and offers more out-of-the-box features like server-side rendering. Docson is lighter but less feature-rich for modern API docs.

How to document TypeScript interfaces with Docson?

Install Typson separately and place it in a 'typson' directory alongside Docson. Then reference your .ts files in Docson URLs, and it will convert interfaces to schemas for documentation, as shown in the Typson example.

Does Docson work with JSON Schema v7?

No, Docson only supports JSON Schema v4, so features from v7 like 'if-then-else' or 'contentEncoding' are not implemented. You'll need to downgrade schemas or use alternatives for newer versions.

How to fix CORS errors when using Docson?

Serve Docson and your schemas from the same web server to avoid cross-origin issues, as recommended in the README. For distributed setups, you may need proxy servers or CORS headers on the schema server.

Can Docson generate static HTML files?

No, Docson dynamically generates documentation in the browser. For static output, you would need to pre-render pages manually or use other tools, as Docson lacks built-in static generation features.

What are the alternatives if Docson lacks features I need?

Consider tools like JSON Schema Faker for mock data, or documentation generators like jsonschema2md for markdown. For full API docs, Redoc or Stoplight support newer JSON Schema versions and offer more integrations.

Open-Awesome

Docson

Apache-2.0JavaScript

A browser-based documentation generator for JSON schemas that renders beautiful, interactive type documentation.

GitHub

497 stars91 forks0 contributors

What is Docson?

Docson is a documentation generator specifically designed for JSON schemas. It takes JSON Schema v4 definitions as input and produces interactive, visually appealing documentation that helps developers understand complex data structures and API contracts. It solves the problem of JSON schemas being difficult to read and navigate in their raw form.

Target Audience

API developers, technical writers, and teams working with JSON-based APIs who need to document their data structures. It's particularly useful for projects using JSON Schema for validation or OpenAPI/Swagger specifications.

Value Proposition

Developers choose Docson because it runs entirely in the browser, requires no server-side processing, and produces documentation that's both beautiful and functional. Its integration capabilities with TypeScript and Swagger make it versatile for modern API development workflows.

Overview

Documentation for your JSON types

Use Cases

Best For

Documenting REST API request/response payloads defined with JSON Schema
Creating interactive documentation for internal JSON-based data formats
Embedding schema documentation directly into wikis or internal documentation sites
Replacing Swagger UI's model documentation with more detailed views
Documenting TypeScript interfaces as JSON schemas for API consumers
Teams needing browser-based schema documentation without server dependencies

Not Ideal For

Projects using JSON Schema v6 or later, as Docson only supports v4 and lacks newer features.
Teams needing static or server-rendered documentation for SEO or offline access, since it runs client-side.
Environments requiring full JSON Schema compliance, due to missing keywords like dependencies and patternProperties.
Quick integration scenarios without manual configuration, given the complex setup for Swagger and TypeScript support.

Pros & Cons

Pros

Browser-Based Execution

Runs entirely in the browser without server-side processing, making deployment simple and reducing server load.

Markdown Descriptions

Renders schema descriptions with markdown formatting, improving readability and documentation clarity.

TypeScript Integration

Supports documenting TypeScript interfaces via Typson conversion, bridging TypeScript and JSON schemas for API documentation.

Swagger UI Enhancement

Replaces Swagger's model documentation with interactive Docson views, offering more detailed schema exploration.

Easy Embedding

Can be embedded into any webpage with a simple script tag, facilitating integration into wikis or internal docs.

Cons

Limited Schema Support

Only supports JSON Schema v4 and admits missing implementations for keywords like dependencies and patternProperties, limiting modern schema use.

Complex Integration Setup

Requires patched versions of Swagger Client and manual styling for Swagger UI integration, adding significant setup overhead.

No Server-Side Rendering

Operates purely client-side, which can hinder performance in SEO-sensitive contexts and requires workarounds for offline usage.

Dependency on Typson

For TypeScript support, it relies on Typson, which must be installed separately and configured, increasing maintenance complexity.

Frequently Asked Questions

Related Projects

jsonschema2pojo

Generate Java types from JSON or JSON Schema and annotate those types for data-binding with Jackson, Gson, etc

Stars6,380

Forks1,676

Last commit4 months ago

JSON Schema + Faker

JSON-Schema + fake data generators

Stars3,449

Forks344

Last commit1 month ago

prmd

JSON Schema tools and doc generation for HTTP APIs

Stars2,089

Forks169

Last commit1 year ago

JSON Schema $Ref Parser

Parse, Resolve, and Dereference JSON Schema $ref pointers in Node and browsers

Stars1,115

Forks250

Last commit2 days ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub