Skip to content
scsiwyg
sign insign up
get startedhow it worksmcpscsiblogcommunityapiplaygroundswaggersign insign up
← all posts

Swagger and OpenAPI: Your Blog Has Documentation

swaggeropenapidocumentation

Swagger and OpenAPI: your blog has documentation

Your blog has a full OpenAPI 3.1 specification. Your blog has interactive Swagger UI. Your blog has machine-readable API documentation that any tool can parse.

When was the last time a blogging platform gave you that?

The OpenAPI spec

Hit /api/openapi.json and you get back a complete OpenAPI 3.1 document. Every endpoint. Every request schema. Every response format. Every error code. Every authentication requirement.

bash
curl https://scsiwyg.com/api/openapi.json | jq '.paths | keys'

This isn't generated from code comments or inferred from route handlers. It's a hand-crafted spec that accurately describes the API contract.

Swagger UI

Visit /docs and you get a full Swagger UI instance. You can:

  • Browse every endpoint with descriptions and examples
  • See request and response schemas with field types
  • Try endpoints live with the "Try it out" button
  • Authenticate with your Bearer token and test write operations

It's the fastest way to understand the API without reading a single line of documentation.

Why this matters

For you

The Swagger UI is the best debugging tool you'll ever have for your blog. Something not publishing? Open Swagger, paste your token, try the POST manually. See the exact error response. Fix the JSON. Try again.

No guessing. No "is it the API or my script?" No staring at curl output trying to figure out what went wrong.

For your AI

When you point an AI IDE at the OpenAPI spec, it can:

  • Understand every endpoint without you explaining anything
  • Generate valid request bodies that match the schema
  • Handle errors based on documented error codes
  • Build complete publishing scripts from the spec alone

The OpenAPI spec is how your AI reads the manual.

# In Claude Code or Cursor:
"Read the OpenAPI spec at /api/openapi.json
 and write a script that publishes all .md files
 in the posts/ directory."

The AI reads the spec, understands the auth, constructs the requests, handles the responses. You get a working script.

For your team

If you're building a content pipeline — CI/CD that publishes on merge, a bot that cross-posts, a dashboard that shows publishing status — the OpenAPI spec is the contract. Generate a TypeScript client from it. Generate tests from it. Generate mocks from it.

bash
npx openapi-typescript https://scsiwyg.com/api/openapi.json -o scsiwyg-types.ts

Documentation as a feature

Most blogging platforms document their API in a wiki page that's three versions behind. scsiwyg documents the API as a first-class endpoint that's always in sync, always machine-readable, and always interactive.

Because if the API is the product, the documentation is part of the product.