Add support for generating an HTTP request documentation snippet
Closes gh-13
This commit is contained in:
Andy Wilkinson
@@ -69,7 +69,7 @@ include::{generated}/error-example/response-fields.asciidoc[]
|
||||
For example, a request that attempts to apply a non-existent tag to a note will produce a
|
||||
`400 Bad Request` response:
|
||||
|
||||
include::{generated}/error-example/response.asciidoc[]
|
||||
include::{generated}/error-example/http-response.asciidoc[]
|
||||
|
||||
[[overview-hypermedia]]
|
||||
== Hypermedia
|
||||
@@ -103,7 +103,7 @@ include::{generated}/index-example/response-fields.asciidoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/index-example/response.asciidoc[]
|
||||
include::{generated}/index-example/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -132,11 +132,11 @@ include::{generated}/notes-list-example/response-fields.asciidoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/notes-list-example/request.asciidoc[]
|
||||
include::{generated}/notes-list-example/curl-request.asciidoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/notes-list-example/response.asciidoc[]
|
||||
include::{generated}/notes-list-example/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -151,11 +151,11 @@ include::{generated}/notes-create-example/request-fields.asciidoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/notes-create-example/request.asciidoc[]
|
||||
include::{generated}/notes-create-example/curl-request.asciidoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/notes-create-example/response.asciidoc[]
|
||||
include::{generated}/notes-create-example/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -177,11 +177,11 @@ include::{generated}/tags-list-example/response-fields.asciidoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tags-list-example/request.asciidoc[]
|
||||
include::{generated}/tags-list-example/curl-request.asciidoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tags-list-example/response.asciidoc[]
|
||||
include::{generated}/tags-list-example/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -196,11 +196,11 @@ include::{generated}/tags-create-example/request-fields.asciidoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tags-create-example/request.asciidoc[]
|
||||
include::{generated}/tags-create-example/curl-request.asciidoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tags-create-example/response.asciidoc[]
|
||||
include::{generated}/tags-create-example/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -229,11 +229,11 @@ include::{generated}/note-get-example/response-fields.asciidoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/note-get-example/request.asciidoc[]
|
||||
include::{generated}/note-get-example/curl-request.asciidoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/note-get-example/response.asciidoc[]
|
||||
include::{generated}/note-get-example/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -250,11 +250,11 @@ To leave an attribute of a note unchanged, any of the above may be omitted from
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/note-update-example/request.asciidoc[]
|
||||
include::{generated}/note-update-example/curl-request.asciidoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/note-update-example/response.asciidoc[]
|
||||
include::{generated}/note-update-example/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -283,11 +283,11 @@ include::{generated}/tag-get-example/response-fields.asciidoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tag-get-example/request.asciidoc[]
|
||||
include::{generated}/tag-get-example/curl-request.asciidoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tag-get-example/response.asciidoc[]
|
||||
include::{generated}/tag-get-example/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -302,8 +302,8 @@ include::{generated}/tag-update-example/request-fields.asciidoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tag-update-example/request.asciidoc[]
|
||||
include::{generated}/tag-update-example/curl-request.asciidoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tag-update-example/response.asciidoc[]
|
||||
include::{generated}/tag-update-example/http-response.asciidoc[]
|
||||
|
||||
@@ -42,12 +42,12 @@ $ java -jar build/libs/*.jar
|
||||
You can check that the service is up and running by executing a simple request using
|
||||
cURL:
|
||||
|
||||
include::{generated}/index/1/request.asciidoc[]
|
||||
include::{generated}/index/1/curl-request.asciidoc[]
|
||||
|
||||
This request should yield the following response in the
|
||||
http://stateless.co/hal_specification.html[Hypertext Application Language (HAL)] format:
|
||||
|
||||
include::{generated}/index/1/response.asciidoc[]
|
||||
include::{generated}/index/1/http-response.asciidoc[]
|
||||
|
||||
Note the `_links` in the JSON response. They are key to navigating the API.
|
||||
|
||||
@@ -59,26 +59,26 @@ Now that you've started the service and verified that it works, the next step is
|
||||
it to create a new note. As you saw above, the URI for working with notes is included as
|
||||
a link when you perform a `GET` request against the root of the service:
|
||||
|
||||
include::{generated}/index/1/response.asciidoc[]
|
||||
include::{generated}/index/1/http-response.asciidoc[]
|
||||
|
||||
To create a note, you need to execute a `POST` request to this URI including a JSON
|
||||
payload containing the title and body of the note:
|
||||
|
||||
include::{generated}/creating-a-note/1/request.asciidoc[]
|
||||
include::{generated}/creating-a-note/1/curl-request.asciidoc[]
|
||||
|
||||
The response from this request should have a status code of `201 Created` and contain a
|
||||
`Location` header whose value is the URI of the newly created note:
|
||||
|
||||
include::{generated}/creating-a-note/1/response.asciidoc[]
|
||||
include::{generated}/creating-a-note/1/http-response.asciidoc[]
|
||||
|
||||
To work with the newly created note you use the URI in the `Location` header. For example,
|
||||
you can access the note's details by performing a `GET` request:
|
||||
|
||||
include::{generated}/creating-a-note/2/request.asciidoc[]
|
||||
include::{generated}/creating-a-note/2/curl-request.asciidoc[]
|
||||
|
||||
This request will produce a response with the note's details in its body:
|
||||
|
||||
include::{generated}/creating-a-note/2/response.asciidoc[]
|
||||
include::{generated}/creating-a-note/2/http-response.asciidoc[]
|
||||
|
||||
Note the `tags` link which we'll make use of later.
|
||||
|
||||
@@ -92,26 +92,26 @@ to tag a note, you must first create the tag.
|
||||
Referring back to the response for the service's index, the URI for working with tags is
|
||||
include as a link:
|
||||
|
||||
include::{generated}/index/1/response.asciidoc[]
|
||||
include::{generated}/index/1/http-response.asciidoc[]
|
||||
|
||||
To create a tag you need to execute a `POST` request to this URI, including a JSON
|
||||
payload containing the name of the tag:
|
||||
|
||||
include::{generated}/creating-a-note/3/request.asciidoc[]
|
||||
include::{generated}/creating-a-note/3/curl-request.asciidoc[]
|
||||
|
||||
The response from this request should have a status code of `201 Created` and contain a
|
||||
`Location` header whose value is the URI of the newly created tag:
|
||||
|
||||
include::{generated}/creating-a-note/3/response.asciidoc[]
|
||||
include::{generated}/creating-a-note/3/http-response.asciidoc[]
|
||||
|
||||
To work with the newly created tag you use the URI in the `Location` header. For example
|
||||
you can access the tag's details by performing a `GET` request:
|
||||
|
||||
include::{generated}/creating-a-note/4/request.asciidoc[]
|
||||
include::{generated}/creating-a-note/4/curl-request.asciidoc[]
|
||||
|
||||
This request will produce a response with the tag's details in its body:
|
||||
|
||||
include::{generated}/creating-a-note/4/response.asciidoc[]
|
||||
include::{generated}/creating-a-note/4/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -132,24 +132,25 @@ with it.
|
||||
Once again we execute a `POST` request. However, this time, in an array named tags, we
|
||||
include the URI of the tag we just created:
|
||||
|
||||
include::{generated}/creating-a-note/5/request.asciidoc[]
|
||||
include::{generated}/creating-a-note/5/curl-request.asciidoc[]
|
||||
|
||||
Once again, the response's `Location` header tells us the URI of the newly created note:
|
||||
|
||||
include::{generated}/creating-a-note/5/response.asciidoc[]
|
||||
include::{generated}/creating-a-note/5/http-response.asciidoc[]
|
||||
|
||||
As before, a `GET` request executed against this URI will retrieve the note's details:
|
||||
|
||||
include::{generated}/creating-a-note/6/request-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/6/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/6/http-response.asciidoc[]
|
||||
|
||||
To verify that the tag has been associated with the note, we can perform a `GET` request
|
||||
against the URI from the `tags` link:
|
||||
|
||||
include::{generated}/creating-a-note/7/request.asciidoc[]
|
||||
include::{generated}/creating-a-note/7/curl-request.asciidoc[]
|
||||
|
||||
The response embeds information about the tag that we've just associated with the note:
|
||||
|
||||
include::{generated}/creating-a-note/7/response.asciidoc[]
|
||||
include::{generated}/creating-a-note/7/http-response.asciidoc[]
|
||||
|
||||
|
||||
|
||||
@@ -159,17 +160,18 @@ An existing note can be tagged by executing a `PATCH` request against the note's
|
||||
a body that contains the array of tags to be associated with the note. We'll used the
|
||||
URI of the untagged note that we created earlier:
|
||||
|
||||
include::{generated}/creating-a-note/8/request.asciidoc[]
|
||||
include::{generated}/creating-a-note/8/curl-request.asciidoc[]
|
||||
|
||||
This request should produce a `204 No Content` response:
|
||||
|
||||
include::{generated}/creating-a-note/8/response.asciidoc[]
|
||||
include::{generated}/creating-a-note/8/http-response.asciidoc[]
|
||||
|
||||
When we first created this note, we noted the tags link included in its details:
|
||||
|
||||
include::{generated}/creating-a-note/2/response.asciidoc[]
|
||||
include::{generated}/creating-a-note/2/http-response.asciidoc[]
|
||||
|
||||
We can use that link now and execute a `GET` request to see that the note now has a
|
||||
single tag:
|
||||
|
||||
include::{generated}/creating-a-note/9/request-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/9/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/9/http-response.asciidoc[]
|
||||
|
||||
Reference in New Issue
Block a user