OpenAPI Documentation #

Romero supports embedding OpenAPI 3.0 specifications directly in your markdown documentation. This allows you to include live API documentation that stays in sync with your spec files.

Basic Usage #

To include an entire OpenAPI specification:

\{{#openapi path/to/your/api.yaml}}

(Without the \)

This will render:

API title, version, and description
All endpoints with their methods, parameters, and responses
Request body schemas
Response schemas

Filtering #

You can filter the rendered documentation to show only specific parts of your API.

Filter by Tag #

Show only endpoints with a specific tag:

\{{#openapi api.yaml#tag=Users}}

Filter by Path #

Show only endpoints matching a path prefix:

\{{#openapi api.yaml#path=/users}}

Filter by Operation ID #

Show a single specific operation:

\{{#openapi api.yaml#operation=getUser}}

Example #

Here’s a complete example using a sample Bookstore API. The spec file is located at example-api.yaml relative to this markdown file.

Bookstore API

v1.0.0

A sample REST API for a bookstore application. This API allows you to manage books, authors, and orders.

#GET `/books`

List all books

Returns a paginated list of all books in the catalog.

Books

Parameters

pageintegerquery

Page number for pagination

limitintegerquery

Number of items per page

genrestringquery

Filter by genre

Responses

dataarray[object]

idstringrequired

Unique identifier for the book

titlestringrequired

The title of the book

authorobject

idstringrequired

Unique identifier for the author

namestringrequired

Author's full name

biostring

Short biography

booksCountinteger

Number of books by this author

isbnstringrequired

ISBN number

genrestring

Book genre

pricenumber

Price in USD

publishedDatestring

Publication date

totalinteger

pageinteger

400 Invalid query parameters

Request

curl -X GET "https://api.bookstore.example.com/v1/books" \  -H "Content-Type: application/json"

const response = await fetch("https://api.bookstore.example.com/v1/books", {  method: "GET",  headers: {    "Content-Type": "application/json",  },});const data = await response.json();

import requestsresponse = requests.get("https://api.bookstore.example.com/v1/books")data = response.json()

req, err := http.NewRequest("GET", "https://api.bookstore.example.com/v1/books", nil)if err != nil {    log.Fatal(err)}req.Header.Set("Content-Type", "application/json")client := &http.Client{}resp, err := client.Do(req)if err != nil {    log.Fatal(err)}defer resp.Body.Close()

Response

{
  "data": [
    {
      "author": {
        "bio": "string",
        "booksCount": 123,
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "string"
      },
      "genre": "string",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "isbn": "string",
      "price": 123.45,
      "publishedDate": "2024-01-15",
      "title": "string"
    }
  ],
  "page": 123,
  "total": 123
}

#POST `/books`

Create a new book

Adds a new book to the catalog.

Books

Request Body

required application/json

titlestringrequired

The title of the book

authorIdstringrequired

ID of the author

isbnstringrequired

ISBN number

genrestring

Book genre

pricenumber

Price in USD

Responses

idstringrequired

Unique identifier for the book

titlestringrequired

The title of the book

authorobject

idstringrequired

Unique identifier for the author

namestringrequired

Author's full name

biostring

Short biography

booksCountinteger

Number of books by this author

isbnstringrequired

ISBN number

genrestring

Book genre

pricenumber

Price in USD

publishedDatestring

Publication date

400 Invalid request body

401 Unauthorized

Request

curl -X POST "https://api.bookstore.example.com/v1/books" \  -H "Content-Type: application/json" \  -d '{  "authorId": "550e8400-e29b-41d4-a716-446655440000",  "genre": "string",  "isbn": "string",  "price": 123.45,  "title": "string"}'

const response = await fetch("https://api.bookstore.example.com/v1/books", {  method: "POST",  headers: {    "Content-Type": "application/json",  },  body: JSON.stringify({  "authorId": "550e8400-e29b-41d4-a716-446655440000",  "genre": "string",  "isbn": "string",  "price": 123.45,  "title": "string"}),});const data = await response.json();

import requestspayload = {  "authorId": "550e8400-e29b-41d4-a716-446655440000",  "genre": "string",  "isbn": "string",  "price": 123.45,  "title": "string"}response = requests.post(    "https://api.bookstore.example.com/v1/books",    json=payload,    headers={"Content-Type": "application/json"})data = response.json()

payload := strings.NewReader(`{  "authorId": "550e8400-e29b-41d4-a716-446655440000",  "genre": "string",  "isbn": "string",  "price": 123.45,  "title": "string"}`)req, err := http.NewRequest("POST", "https://api.bookstore.example.com/v1/books", payload)if err != nil {    log.Fatal(err)}req.Header.Set("Content-Type", "application/json")client := &http.Client{}resp, err := client.Do(req)if err != nil {    log.Fatal(err)}defer resp.Body.Close()

Response

{
  "author": {
    "bio": "string",
    "booksCount": 123,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string"
  },
  "genre": "string",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "isbn": "string",
  "price": 123.45,
  "publishedDate": "2024-01-15",
  "title": "string"
}

#GET `/books/{bookId}`

Get a book by ID

Returns detailed information about a specific book.

Books

Parameters

bookIdstringrequiredpath

The unique identifier of the book

Responses

idstringrequired

Unique identifier for the book

titlestringrequired

The title of the book

authorobject

idstringrequired

Unique identifier for the author

namestringrequired

Author's full name

biostring

Short biography

booksCountinteger

Number of books by this author

isbnstringrequired

ISBN number

genrestring

Book genre

pricenumber

Price in USD

publishedDatestring

Publication date

404 Book not found

Request

curl -X GET "https://api.bookstore.example.com/v1/books/{bookId}" \  -H "Content-Type: application/json"

const response = await fetch("https://api.bookstore.example.com/v1/books/{bookId}", {  method: "GET",  headers: {    "Content-Type": "application/json",  },});const data = await response.json();

import requestsresponse = requests.get("https://api.bookstore.example.com/v1/books/{bookId}")data = response.json()

req, err := http.NewRequest("GET", "https://api.bookstore.example.com/v1/books/{bookId}", nil)if err != nil {    log.Fatal(err)}req.Header.Set("Content-Type", "application/json")client := &http.Client{}resp, err := client.Do(req)if err != nil {    log.Fatal(err)}defer resp.Body.Close()

Response

{
  "author": {
    "bio": "string",
    "booksCount": 123,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string"
  },
  "genre": "string",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "isbn": "string",
  "price": 123.45,
  "publishedDate": "2024-01-15",
  "title": "string"
}

#PUT `/books/{bookId}`

Update a book

Updates an existing book's information.

Books

Parameters

bookIdstringrequiredpath

The unique identifier of the book

Request Body

required application/json

titlestringrequired

The title of the book

authorIdstringrequired

ID of the author

isbnstringrequired

ISBN number

genrestring

Book genre

pricenumber

Price in USD

Responses

idstringrequired

Unique identifier for the book

titlestringrequired

The title of the book

authorobject

idstringrequired

Unique identifier for the author

namestringrequired

Author's full name

biostring

Short biography

booksCountinteger

Number of books by this author

isbnstringrequired

ISBN number

genrestring

Book genre

pricenumber

Price in USD

publishedDatestring

Publication date

401 Unauthorized

404 Book not found

Request

curl -X PUT "https://api.bookstore.example.com/v1/books/{bookId}" \  -H "Content-Type: application/json" \  -d '{  "authorId": "550e8400-e29b-41d4-a716-446655440000",  "genre": "string",  "isbn": "string",  "price": 123.45,  "title": "string"}'

const response = await fetch("https://api.bookstore.example.com/v1/books/{bookId}", {  method: "PUT",  headers: {    "Content-Type": "application/json",  },  body: JSON.stringify({  "authorId": "550e8400-e29b-41d4-a716-446655440000",  "genre": "string",  "isbn": "string",  "price": 123.45,  "title": "string"}),});const data = await response.json();

import requestspayload = {  "authorId": "550e8400-e29b-41d4-a716-446655440000",  "genre": "string",  "isbn": "string",  "price": 123.45,  "title": "string"}response = requests.put(    "https://api.bookstore.example.com/v1/books/{bookId}",    json=payload,    headers={"Content-Type": "application/json"})data = response.json()

payload := strings.NewReader(`{  "authorId": "550e8400-e29b-41d4-a716-446655440000",  "genre": "string",  "isbn": "string",  "price": 123.45,  "title": "string"}`)req, err := http.NewRequest("PUT", "https://api.bookstore.example.com/v1/books/{bookId}", payload)if err != nil {    log.Fatal(err)}req.Header.Set("Content-Type", "application/json")client := &http.Client{}resp, err := client.Do(req)if err != nil {    log.Fatal(err)}defer resp.Body.Close()

Response

{
  "author": {
    "bio": "string",
    "booksCount": 123,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string"
  },
  "genre": "string",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "isbn": "string",
  "price": 123.45,
  "publishedDate": "2024-01-15",
  "title": "string"
}

#DELETE `/books/{bookId}`

Delete a book

Removes a book from the catalog.

Books

Parameters

bookIdstringrequiredpath

The unique identifier of the book

Responses

204 Book deleted successfully

401 Unauthorized

404 Book not found

Request

curl -X DELETE "https://api.bookstore.example.com/v1/books/{bookId}" \  -H "Content-Type: application/json"

const response = await fetch("https://api.bookstore.example.com/v1/books/{bookId}", {  method: "DELETE",  headers: {    "Content-Type": "application/json",  },});const data = await response.json();

import requestsresponse = requests.delete("https://api.bookstore.example.com/v1/books/{bookId}")data = response.json()

req, err := http.NewRequest("DELETE", "https://api.bookstore.example.com/v1/books/{bookId}", nil)if err != nil {    log.Fatal(err)}req.Header.Set("Content-Type", "application/json")client := &http.Client{}resp, err := client.Do(req)if err != nil {    log.Fatal(err)}defer resp.Body.Close()

Response

No response body

#GET `/authors`

List all authors

Returns a list of all authors.

Authors

Responses

200 A list of authors

Request

curl -X GET "https://api.bookstore.example.com/v1/authors" \  -H "Content-Type: application/json"

const response = await fetch("https://api.bookstore.example.com/v1/authors", {  method: "GET",  headers: {    "Content-Type": "application/json",  },});const data = await response.json();

import requestsresponse = requests.get("https://api.bookstore.example.com/v1/authors")data = response.json()

req, err := http.NewRequest("GET", "https://api.bookstore.example.com/v1/authors", nil)if err != nil {    log.Fatal(err)}req.Header.Set("Content-Type", "application/json")client := &http.Client{}resp, err := client.Do(req)if err != nil {    log.Fatal(err)}defer resp.Body.Close()

Response

[
  {
    "bio": "string",
    "booksCount": 123,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string"
  }
]

#GET `/authors/{authorId}`

Get an author by ID

Returns detailed information about a specific author.

Authors

Parameters

authorIdstringrequiredpath

The unique identifier of the author

Responses

idstringrequired

Unique identifier for the author

namestringrequired

Author's full name

biostring

Short biography

booksCountinteger

Number of books by this author

404 Author not found

Request

curl -X GET "https://api.bookstore.example.com/v1/authors/{authorId}" \  -H "Content-Type: application/json"

const response = await fetch("https://api.bookstore.example.com/v1/authors/{authorId}", {  method: "GET",  headers: {    "Content-Type": "application/json",  },});const data = await response.json();

import requestsresponse = requests.get("https://api.bookstore.example.com/v1/authors/{authorId}")data = response.json()

req, err := http.NewRequest("GET", "https://api.bookstore.example.com/v1/authors/{authorId}", nil)if err != nil {    log.Fatal(err)}req.Header.Set("Content-Type", "application/json")client := &http.Client{}resp, err := client.Do(req)if err != nil {    log.Fatal(err)}defer resp.Body.Close()

Response

{
  "bio": "string",
  "booksCount": 123,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string"
}

#POST `/orders`

Create a new order

Places a new order for books.

Orders

Request Body

required application/json

itemsarray[object]required

bookIdstring

quantityinteger

shippingAddressstringrequired

Delivery address

Responses

idstringrequired

Unique order identifier

itemsarray[object]required

bookobject

idstringrequired

Unique identifier for the book

titlestringrequired

The title of the book

authorobject

idstringrequired

Unique identifier for the author

namestringrequired

Author's full name

biostring

Short biography

booksCountinteger

Number of books by this author

isbnstringrequired

ISBN number

genrestring

Book genre

pricenumber

Price in USD

publishedDatestring

Publication date

quantityinteger

totalnumber

Total order amount

statusstringrequiredenum: pending, processing, shipped, delivered

Current order status

createdAtstring

Order creation timestamp

400 Invalid order data

401 Unauthorized

Request

curl -X POST "https://api.bookstore.example.com/v1/orders" \  -H "Content-Type: application/json" \  -d '{  "items": [    {      "bookId": "550e8400-e29b-41d4-a716-446655440000",      "quantity": 123    }  ],  "shippingAddress": "string"}'

const response = await fetch("https://api.bookstore.example.com/v1/orders", {  method: "POST",  headers: {    "Content-Type": "application/json",  },  body: JSON.stringify({  "items": [    {      "bookId": "550e8400-e29b-41d4-a716-446655440000",      "quantity": 123    }  ],  "shippingAddress": "string"}),});const data = await response.json();

import requestspayload = {  "items": [    {      "bookId": "550e8400-e29b-41d4-a716-446655440000",      "quantity": 123    }  ],  "shippingAddress": "string"}response = requests.post(    "https://api.bookstore.example.com/v1/orders",    json=payload,    headers={"Content-Type": "application/json"})data = response.json()

payload := strings.NewReader(`{  "items": [    {      "bookId": "550e8400-e29b-41d4-a716-446655440000",      "quantity": 123    }  ],  "shippingAddress": "string"}`)req, err := http.NewRequest("POST", "https://api.bookstore.example.com/v1/orders", payload)if err != nil {    log.Fatal(err)}req.Header.Set("Content-Type", "application/json")client := &http.Client{}resp, err := client.Do(req)if err != nil {    log.Fatal(err)}defer resp.Body.Close()

Response

{
  "createdAt": "2024-01-15T09:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "items": [
    {
      "book": {
        "author": {
          "bio": "string",
          "booksCount": 123,
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "string"
        },
        "genre": "string",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "isbn": "string",
        "price": 123.45,
        "publishedDate": "2024-01-15",
        "title": "string"
      },
      "quantity": 123
    }
  ],
  "status": "string",
  "total": 123.45
}

OpenAPI Documentation #

Basic Usage #

Filtering #

Filter by Tag #

Filter by Path #

Filter by Operation ID #

Example #

Bookstore API

#GET /books

Parameters

Responses

#POST /books

Request Body

Responses

#GET /books/{bookId}

Parameters

Responses

#PUT /books/{bookId}

Parameters

Request Body

Responses

#DELETE /books/{bookId}

Parameters

Responses

#GET /authors

Responses

#GET /authors/{authorId}

Parameters

Responses

#POST /orders

Request Body

Responses

#GET `/books`

#POST `/books`

#GET `/books/{bookId}`

#PUT `/books/{bookId}`

#DELETE `/books/{bookId}`

#GET `/authors`

#GET `/authors/{authorId}`

#POST `/orders`