Add a sample showing how to use Spring REST Docs with Slate
Closes gh-124
This commit is contained in:
Andy Wilkinson
206
samples/rest-notes-slate/slate/source/api-guide.md.erb
Normal file
206
samples/rest-notes-slate/slate/source/api-guide.md.erb
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
title: REST Notes API Guide
|
||||
|
||||
language_tabs:
|
||||
- shell
|
||||
- http
|
||||
|
||||
search: true
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
|
||||
## HTTP verbs
|
||||
|
||||
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
|
||||
use of HTTP verbs.
|
||||
|
||||
|
||||
Verb | Usage
|
||||
-------- | -----
|
||||
`GET` | Used to retrieve a resource
|
||||
`POST` | Used to create a new resource
|
||||
`PATCH` | Used to update an existing resource, including partial updates
|
||||
`DELETE` | Used to delete an existing resource
|
||||
|
||||
## HTTP status codes
|
||||
|
||||
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
|
||||
use of HTTP status codes.
|
||||
|
||||
Status code | Usage
|
||||
----------------- | -----
|
||||
`200 OK` | The request completed successfully
|
||||
`201 Created` | A new resource has been created successfully. The resource's URI is available from the response's `Location` header
|
||||
`204 No Content` | An update to an existing resource has been applied successfully
|
||||
`400 Bad Request` | The request was malformed. The response body will include an error providing further information
|
||||
`404 Not Found` | The requested resource did not exist
|
||||
|
||||
## Errors
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/error-example/http-response.md")).result(binding) %>
|
||||
|
||||
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object
|
||||
that describes the problem. The error object has the following structure:
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/error-example/response-fields.md")).result(binding) %>
|
||||
|
||||
## Hypermedia
|
||||
|
||||
RESTful Notes uses hypermedia and resources include links to other resources in their
|
||||
responses. Responses are in [Hypertext Application Language (HAL)](http://stateless.co/hal_specification.html format).
|
||||
Links can be found beneath the `_links` key. Users of the API should not create URIs
|
||||
themselves, instead they should use the above-described links to navigate
|
||||
|
||||
|
||||
|
||||
# Resources
|
||||
|
||||
|
||||
|
||||
## Index
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/index-example/curl-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/index-example/http-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/index-example/http-response.md")).result(binding) %>
|
||||
|
||||
The index provides the entry point into the service. A `GET` request is used to access the index.
|
||||
|
||||
### Response structure
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/index-example/response-fields.md")).result(binding) %>
|
||||
|
||||
### Links
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/index-example/links.md")).result(binding) %>
|
||||
|
||||
|
||||
|
||||
## Notes
|
||||
|
||||
The Notes resources is used to create and list notes
|
||||
|
||||
### Listing notes
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/http-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/http-response.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/curl-request.md")).result(binding) %>
|
||||
|
||||
A `GET` request will list all of the service's notes.
|
||||
|
||||
#### Response structure
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/response-fields.md")).result(binding) %>
|
||||
|
||||
### Creating a note
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/http-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/http-response.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/curl-request.md")).result(binding) %>
|
||||
|
||||
A `POST` request is used to create a note
|
||||
|
||||
#### Request structure
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/request-fields.md")).result(binding) %>
|
||||
|
||||
|
||||
|
||||
## Tags
|
||||
|
||||
The Tags resource is used to create and list tags.
|
||||
|
||||
### Listing tags
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/curl-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/http-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/http-response.md")).result(binding) %>
|
||||
|
||||
A `GET` request will list all of the service's tags.
|
||||
|
||||
#### Response structure
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/response-fields.md")).result(binding) %>
|
||||
|
||||
|
||||
### Creating a tag
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tags-create-example/curl-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tags-create-example/http-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/http-response.md")).result(binding) %>
|
||||
|
||||
A `POST` request is used to create a tag
|
||||
|
||||
#### Request structure
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tags-create-example/request-fields.md")).result(binding) %>
|
||||
|
||||
|
||||
|
||||
## Note
|
||||
|
||||
The Note resource is used to retrieve, update, and delete individual notes
|
||||
|
||||
### Retrieve a note
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/http-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/curl-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/http-response.md")).result(binding) %>
|
||||
|
||||
A `GET` request will retrieve the details of a note
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/response-fields.md")).result(binding) %>
|
||||
|
||||
#### Links
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/links.md")).result(binding) %>
|
||||
|
||||
### Update a note
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/curl-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/http-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/http-response.md")).result(binding) %>
|
||||
|
||||
A `PATCH` request is used to update a note
|
||||
|
||||
#### Request structure
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/request-fields.md")).result(binding) %>
|
||||
|
||||
To leave an attribute of a note unchanged, any of the above may be omitted from the
|
||||
request.
|
||||
|
||||
|
||||
|
||||
## Tag
|
||||
|
||||
The Tag resource is used to retrieve, update, and delete individual tags
|
||||
|
||||
### Retrieve a tag
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/curl-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/http-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/http-response.md")).result(binding) %>
|
||||
|
||||
A `GET` request will retrieve the details of a tag
|
||||
|
||||
#### Response structure
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/response-fields.md")).result(binding) %>
|
||||
|
||||
#### Links
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/links.md")).result(binding) %>
|
||||
|
||||
### Update a tag
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/curl-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/http-request.md")).result(binding) %>
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/http-response.md")).result(binding) %>
|
||||
|
||||
A `PATCH` request is used to update a tag
|
||||
|
||||
#### Request structure
|
||||
|
||||
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/request-fields.md")).result(binding) %>
|
||||
Reference in New Issue
Block a user