Skip to content

Instantly share code, notes, and snippets.

@azagniotov

azagniotov/beautiful.rest.api.docs.in.markdown.md

Last active April 7, 2024 16:39
Show Gist options
  • Save azagniotov/a4b16faf0febd12efbc6c3d7370383a6 to your computer and use it in GitHub Desktop.
Save azagniotov/a4b16faf0febd12efbc6c3d7370383a6 to your computer and use it in GitHub Desktop.
Download ZIP
Example to create beautiful REST API docs in Markdown, inspired by Swagger API docs.
Raw
beautiful.rest.api.docs.in.markdown.md

Create beautiful REST API docs authored in Markdown

Creating new/overwriting existing stubs & proxy configs

POST / (overwrites all in-memory stub and/or proxy-config)
Parameters
name type data type description
None required object (JSON or YAML) N/A
Responses
http code content-type response
201 text/plain;charset=UTF-8 Configuration created successfully
400 application/json {"code":"400","message":"Bad Request"}
405 text/html;charset=utf-8 None
Example cURL
 curl -X POST -H "Content-Type: application/json" --data @post.json http://localhost:8889/

Listing existing stubs & proxy configs as YAML string

GET / (gets all in-memory stub & proxy configs)
Parameters

None

Responses
http code content-type response
200 text/plain;charset=UTF-8 YAML string
Example cURL
 curl -X GET -H "Content-Type: application/json" http://localhost:8889/
GET /{stub_numeric_id} (gets stub by its resource-id-{stub_numeric_id} in the YAML config)
Parameters
name type data type description
stub_numeric_id required int ($int64) The specific stub numeric id
Responses
http code content-type response
200 text/plain;charset=UTF-8 YAML string
400 application/json {"code":"400","message":"Bad Request"}
Example cURL
 curl -X GET -H "Content-Type: application/json" http://localhost:8889/0
GET /{uuid} (gets stub by its defined uuid property)
Parameters
name type data type description
uuid required string The specific stub unique idendifier
Responses
http code content-type response
200 text/plain;charset=UTF-8 YAML string
400 application/json {"code":"400","message":"Bad Request"}
Example cURL
 curl -X GET -H "Content-Type: application/json" http://localhost:8889/some-unique-uuid-string
GET /proxy-config/default (gets default proxy-config)
Parameters

None

Responses
http code content-type response
200 text/plain;charset=UTF-8 YAML string
400 application/json {"code":"400","message":"Bad Request"}
Example cURL
 curl -X GET -H "Content-Type: application/json" http://localhost:8889/proxy-config/default
GET /proxy-config/{uuid} (gets proxy config by its uuid property)
Parameters
name type data type description
uuid required string The specific proxy config unique idendifier
Responses
http code content-type response
200 text/plain;charset=UTF-8 YAML string
400 application/json {"code":"400","message":"Bad Request"}
Example cURL
 curl -X GET -H "Content-Type: application/json" http://localhost:8889/proxy-config/some-unique-uuid-string

Updating existing stubs & proxy configs

PUT /{stub_numeric_id} (updates stub by its resource-id-{stub_numeric_id} in the config)
Parameters
name type data type description
stub_numeric_id required int ($int64) The specific stub numeric id
Responses
http code content-type response
201 text/plain;charset=UTF-8 Stub request index#<stub_numeric_id> updated successfully"
400 application/json {"code":"400","message":"Bad Request"}
405 text/html;charset=utf-8 None
Example cURL
 curl -X PUT -H "Content-Type: application/json" --data @put.json http://localhost:8889/0
PUT /{uuid} (updates stub by its defined uuid property)
Parameters
name type data type description
uuid required string The specific stub unique idendifier
Responses
http code content-type response
201 text/plain;charset=UTF-8 Stub request uuid#<uuid> updated successfully
400 application/json {"code":"400","message":"Bad Request"}
405 text/html;charset=utf-8 None
Example cURL
 curl -X PUT -H "Content-Type: application/json" --data @put.json http://localhost:8889/some-unique-uuid-string
PUT /proxy-config/default (updates default proxy-config)
Parameters

None

Responses
http code content-type response
201 text/plain;charset=UTF-8 Proxy config uuid#default updated successfully
400 application/json {"code":"400","message":"Bad Request"}
405 text/html;charset=utf-8 None
Example cURL
 curl -X PUT -H "Content-Type: application/json" --data @put.json http://localhost:8889/proxy-config/default
PUT /proxy-config/{uuid} (updates proxy-config by its uuid property)
Parameters
name type data type description
uuid required string The specific proxy config unique idendifier
Responses
http code content-type response
201 text/plain;charset=UTF-8 Proxy config uuid#<uuid> updated successfully
400 application/json {"code":"400","message":"Bad Request"}
405 text/html;charset=utf-8 None
Example cURL
 curl -X PUT -H "Content-Type: application/json" --data @put.json http://localhost:8889/proxy-config/some-unique-uuid-string

Deleting existing stubs & proxy configs

DELETE / (deletes all in-memory stub & proxy configs)
Parameters

None

Responses
http code content-type response
200 text/plain;charset=UTF-8 All in-memory YAML config was deleted successfully
Example cURL
 curl -X DELETE -H "Content-Type: application/json" http://localhost:8889/
DELETE /{stub_numeric_id} (deletes stub by its resource-id-{stub_numeric_id} in the config)
Parameters
name type data type description
stub_numeric_id required int ($int64) The specific stub numeric id
Responses
http code content-type response
200 text/plain;charset=UTF-8 Stub request index#<stub_numeric_id> deleted successfully
400 application/json {"code":"400","message":"Bad Request"}
Example cURL
 curl -X DELETE -H "Content-Type: application/json" http://localhost:8889/0
DELETE /{uuid} (updates stub by its defined uuid property)
Parameters
name type data type description
uuid required string The specific stub unique idendifier
Responses
http code content-type response
200 text/plain;charset=UTF-8 Stub request uuid#<uuid> deleted successfully
400 application/json {"code":"400","message":"Bad Request"}
Example cURL
 curl -X DELETE -H "Content-Type: application/json" http://localhost:8889/some-unique-uuid-string
DELETE /proxy-config/{uuid} (deletes proxy-config by its uuid property)
Parameters
name type data type description
uuid required string The specific proxy config unique idendifier
Responses
http code content-type response
200 text/plain;charset=UTF-8 Proxy config uuid#<uuid> deleted successfully
400 application/json {"code":"400","message":"Bad Request"}
Example cURL
 curl -X DELETE -H "Content-Type: application/json" http://localhost:8889/proxy-config/some-unique-uuid-string
@vianho
Copy link

vianho commented Jan 4, 2022

This is beautiful, thank you for sharing!
Will be using this in my school project 👀

@SvS30
Copy link

SvS30 commented Jun 1, 2022

Amazing, thank u! 👍

@thiagonobrega
Copy link

Awesome. thank you for sharing

@weidali
Copy link

weidali commented May 23, 2023

Thanks!

@vn7n24fzkq
Copy link

Thanks! I was googling 'markdown API documentation' and just arrived here.

@dariocastroQHR
Copy link

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment