From 8e26fb3394b1fcb013a7b51c900e690c46dfee48 Mon Sep 17 00:00:00 2001 From: Vincent Verbruggen Date: Wed, 26 Nov 2025 14:52:38 +0100 Subject: [PATCH] vault backup: 2025-11-26 14:52:38 --- Work/Random/API Documentation Tools.md | 78 ++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 Work/Random/API Documentation Tools.md diff --git a/Work/Random/API Documentation Tools.md b/Work/Random/API Documentation Tools.md new file mode 100644 index 0000000..60ae275 --- /dev/null +++ b/Work/Random/API Documentation Tools.md @@ -0,0 +1,78 @@ +# API Documentation Tools - Swagger Alternatives + +Alternatives to Swagger UI that address common pain points: +- Attribute descriptions hidden behind clicks (Swagger hides detailed descriptions) +- Need for code examples in multiple programming languages +- OpenAPI 3.0 compatibility required + +## Recommendations + +### 1. Scalar (Best Free Option) +- **Website**: https://scalar.com/ +- **Code examples**: Built-in code snippet generator for multiple languages and HTTP clients (copy-paste ready) +- **Descriptions**: Modern UI with better information architecture than Swagger - descriptions more visible +- **OpenAPI**: Full 3.0 support +- **Interactive**: "Try It" functionality for testing endpoints directly +- **Cost**: Free and open-source +- **Self-hosted**: Yes + +### 2. Mintlify +- **Website**: https://www.mintlify.com/ +- **Code examples**: Supports x-codeSamples extension, displays code in cURL, Python, JavaScript and more. Can integrate with liblab/Stainless for SDK code samples +- **Descriptions**: Clean layout with visible attribute descriptions +- **OpenAPI**: 3.0+ support, webhooks supported in 3.1+ +- **Interactive**: API playground with live responses, supports multiple server environments +- **Cost**: Tiered pricing (free tier available) +- **Extra**: SOC 2, GDPR, ISO/27001 compliance, SAML SSO for enterprise + +### 3. Bump.sh (Best for Teams) +- **Website**: https://bump.sh/ +- **Code examples**: Supports x-codeSamples in OpenAPI specs +- **Descriptions**: 3-column Stripe-style layout - information immediately visible +- **OpenAPI**: 3.0/3.1 supported (3.1 on day of release) +- **Interactive**: Enhanced API Explorer with form-based interfaces +- **Cost**: Paid service +- **Extra**: Automatic changelog generation, access control, custom branding, SSO + +### 4. Redocly (Enterprise) +- **Website**: https://redocly.com/ +- **Code examples**: Auto-generated in multiple languages (paid feature only) +- **Descriptions**: Clean three-panel layout with expandable sections +- **OpenAPI**: Full 3.0 support, deep ecosystem integration +- **Interactive**: Read-only in free version +- **Cost**: Free (Redoc) / Paid (Redocly) +- **Note**: Free "Redoc" version does NOT include auto-generated code samples + +### 5. Stoplight +- **Website**: https://stoplight.io/ +- **Code examples**: Generates client SDKs in various languages +- **Descriptions**: Interactive documentation with better visibility than Swagger +- **OpenAPI**: Full 3.0 support +- **Cost**: Paid +- **Extra**: Also includes API design and governance tools + +## Quick Comparison + +| Feature | Scalar | Mintlify | Bump.sh | Redocly | Stoplight | +|--------------------------|--------|----------|---------|---------|-----------| +| Multi-lang code samples | Yes | Yes | Yes | Paid | Yes | +| OpenAPI 3.0 | Yes | Yes | Yes | Yes | Yes | +| Interactive testing | Yes | Yes | Yes | No | Yes | +| Self-hosted option | Yes | No | No | Yes | No | +| Free tier | Yes | Yes | No | Yes | No | +| x-codeSamples support | Yes | Yes | Yes | Yes | Yes | + +## Decision Guide + +- **Free + Self-hosted + Full features**: Scalar +- **Best documentation UX**: Mintlify or Bump.sh +- **Enterprise with compliance needs**: Mintlify or Redocly +- **API design + documentation**: Stoplight +- **Automatic changelogs**: Bump.sh + +## Sources + +- [Mintlify OpenAPI Setup](https://www.mintlify.com/docs/api-playground/openapi-setup) +- [Bump.sh vs Swagger UI](https://bump.sh/compare/swagger-ui/) +- [Speakeasy - Choosing a docs vendor](https://www.speakeasy.com/blog/choosing-a-docs-vendor) +- [Stack Overflow - Swagger UI alternatives](https://stackoverflow.com/questions/36634281/list-of-swagger-ui-alternatives)