Skip to content

Instantly share code, notes, and snippets.

@azagniotov
Last active November 30, 2024 16:23
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.
Example to create beautiful REST API docs in Markdown, inspired by Swagger API docs.

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

@vn7n24fzkq
Copy link

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

@dariocastroQHR
Copy link

Thanks!

@germangutierrezv
Copy link

Thnaks

@YtimoDeng
Copy link

It's good, Thanks!

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