vault backup: 2025-11-26 14:52:38

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)