See the difference
The same endpoint. One is human-readable.
---
method: GET
path: /users/{userId}
operationId: get-user
tags: [Users]
---
# Get User
Returns a user by ID.
```omg.path
{ userId: uuid }
```
```omg.response
{
id: uuid,
email: string @format("email"),
name: string,
role: "admin" | "user" | "guest",
createdAt: datetime
}
```
openapi: 3.1.0
paths:
/users/{userId}:
get:
operationId: get-user
tags: [Users]
summary: Get User
description: Returns a user by ID.
parameters:
- name: userId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required: [id, email, name, role, createdAt]
properties:
id:
type: string
format: uuid
email:
type: string
format: email
name:
type: string
role:
type: string
enum: [admin, user, guest]
createdAt:
type: string
format: date-time
Why OMG?
Markdown Native
Write in familiar Markdown with YAML frontmatter. Technical writers and developers can collaborate without learning new syntax.
DRY with Partials
Define errors, pagination, and auth once. Include them anywhere with {{> partials/errors }}. No more copy-pasting.
Full OpenAPI 3.1
Compiles to standard OpenAPI. Use your existing tools for code generation, documentation, and testing.
Type-Safe Schemas
Concise type syntax with constraints: string @minLength(1), integer @min(0), "a" | "b" enums, Type[] arrays.
IDE Support
VS Code extension with syntax highlighting, autocomplete, and diagnostics. Catch errors as you type.
CLI Tooling
Build, lint, format, and parse commands. Integrate into your CI/CD pipeline with ease.
Get started in seconds
Install
npm install -g omg-md-cli
Initialize
omg init my-api
Build
omg build api.omg.md -o openapi.yaml
Ready to simplify your API specs?
Join developers who write API documentation they actually enjoy reading.