What does MICROSERVICE.md™ generate?

From a single MICROSERVICE.md™ file, the wizard generates: openapi.yaml (REST API contract), asyncapi.yaml (event-driven contract), runbook.md (operational playbook), canvas.md (architecture canvas), and context-pack.md (AI context file).

// AI-READY DOCUMENTATION SPECIFICATION

Introducing
MICROSERVICE.md

Q: Who is MICROSERVICE.md™ for?

MICROSERVICE.md™ is built for dev teams building or maintaining microservices, platform engineers who need a consistent documentation specification across their org, and AI-first teams using LLMs and coding agents that need rich structured context.

MICROSERVICE.md™ is a lightweight, AI-ready documentation specification for microservice systems, created by Koesion.

→ Try it free

Microservice documentation is broken.

Docs rot immediately.

Your OpenAPI spec drifts from reality the moment the first PR merges.

Every team invents their own format.

Runbooks in Notion, contracts in Confluence, specs in git — no single source of truth.

AI agents are flying blind.

LLMs can't build on a service they know nothing about. README files don't cut it.

Onboarding is painful.

New engineers spend days mapping dependencies that should be obvious.

What is MICROSERVICE.md™?

MICROSERVICE.md™ is a structured documentation file — one per service — that becomes the canonical source of truth for your microservice.

You fill it once through a guided wizard. From it, we generate every artifact your team, your tools, and your AI agents need.

# microservice.md

name: payment-svc

team: payments

tier: critical

interfaces:

- REST /v1/charge

- event: charge.completed

dependencies:

- ledger-svc

- fraud-svc

slo:

p99: 200ms

uptime: 99.95%

The structure of a MICROSERVICE.md™ file

Every MICROSERVICE.md™ file is divided into five sections. Together they form a complete, machine-readable portrait of your service.

01 — IDENTITY

Who is this service?

Name, mission statement, bounded context, and ownership. This section answers the most fundamental question: what is this service responsible for and who owns it?

name: payment-svc mission: Processes charges and manages payment lifecycle boundedContext: Billing owner: team: payments-team oncall: pagerduty://payments

02 — INTERFACES

How does it communicate?

REST endpoints, GraphQL schema, gRPC proto, published events, and consumed events. This section drives the generated OpenAPI and AsyncAPI specs.

interfaces: rest: - POST /v1/charge - GET /v1/charge/:id publishedEvents: - charge.completed - charge.failed consumedEvents: - order.created

03 — DATA & DEPENDENCIES

What does it own and rely on?

Datastores the service owns, synchronous service dependencies with criticality and resilience patterns, and async event consumers.

ownedData: - postgres: charges - redis: session-cache syncDeps: - service: fraud-svc criticality: hard resilience: [circuit-breaker] - service: ledger-svc criticality: hard

04 — OPERATIONS

How does it behave in production?

SLOs, security model (authn/authz, PII handling, scopes), and deployment configuration. This section powers the generated runbook and canvas.

slo: availability: 99.95% latencyP99: 200ms security: authn: JWT (Auth0) hasPii: true deployment: platform: kubernetes replicas: 3

05 — OBSERVABILITY

How do you know it's healthy?

Log format, key metrics, distributed tracing, dashboards, and alerts. The last piece the AI context pack needs to help diagnose incidents.

observability: logs: structured JSON metrics: - charge_success_total - charge_latency_p99 traces: true alerts: - error_rate > 1%

One wizard. Five artifacts.

Everything your team needs.

openapi.yamlMachine-readable REST API contract. Powers Swagger UI, client codegen, and API gateways.

asyncapi.yamlEvent-driven contract for Kafka, SNS, and other async interfaces.

runbook.mdOperational playbook — alerts, escalation paths, common failure modes.

canvas.mdArchitecture canvas — visual overview of the service for design reviews and onboarding.

context-pack.mdStructured AI context file — drop it in your agent's context window and it knows everything about your service.

Who it's for

Dev teams

Building or maintaining microservices who want docs that stay current without manual effort.

Platform engineers

Who need a consistent documentation specification across every service in the org.

AI-first teams

Using LLMs and coding agents that need rich, structured context to generate correct code.

Ready to document your first microservice?

Free during beta. No credit card required.

→ Get started free

IntroducingMICROSERVICE.md