Skip to content

Instantly share code, notes, and snippets.

@keiranlovett

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

Forked from azagniotov/beautiful.rest.api.docs.in.markdown.md
Created June 26, 2023 17:58
Show Gist options
  • Save keiranlovett/6649178cc2a15af271f8ede972122568 to your computer and use it in GitHub Desktop.
Save keiranlovett/6649178cc2a15af271f8ede972122568 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment