Align with the Asciidoctor team's preferred file extension, .adoc
Closes gh-45
This commit is contained in:
Andy Wilkinson
10
README.md
10
README.md
@@ -279,9 +279,9 @@ command for the request and the resulting response to files in a directory named
|
||||
`index` in the project's `build/generated-snippets/` directory. Three files will
|
||||
be written:
|
||||
|
||||
- `index/curl-request.asciidoc`
|
||||
- `index/http-request.asciidoc`
|
||||
- `index/http-response.asciidoc`
|
||||
- `index/curl-request.adoc`
|
||||
- `index/http-request.adoc`
|
||||
- `index/http-response.adoc`
|
||||
|
||||
#### Parameterized output directories
|
||||
|
||||
@@ -340,8 +340,8 @@ which the snippets are written. For example, to include both the request and res
|
||||
snippets described above:
|
||||
|
||||
```
|
||||
include::{generated}/index/curl-request.asciidoc[]
|
||||
include::{generated}/index/http-response.asciidoc[]
|
||||
include::{generated}/index/curl-request.adoc[]
|
||||
include::{generated}/index/http-response.adoc[]
|
||||
```
|
||||
|
||||
## Generating snippets in your IDE
|
||||
|
||||
@@ -64,12 +64,12 @@ use of HTTP status codes.
|
||||
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:
|
||||
|
||||
include::{generated}/error-example/response-fields.asciidoc
|
||||
include::{generated}/error-example/response-fields.adoc[]
|
||||
|
||||
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/http-response.asciidoc[]
|
||||
include::{generated}/error-example/http-response.adoc[]
|
||||
|
||||
[[overview-hypermedia]]
|
||||
== Hypermedia
|
||||
@@ -99,18 +99,18 @@ A `GET` request is used to access the index
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/index-example/response-fields.asciidoc[]
|
||||
include::{generated}/index-example/response-fields.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/index-example/http-response.asciidoc[]
|
||||
include::{generated}/index-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-index-links]]
|
||||
==== Links
|
||||
|
||||
include::{generated}/index-example/links.asciidoc[]
|
||||
include::{generated}/index-example/links.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -128,15 +128,15 @@ A `GET` request will list all of the service's notes.
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/notes-list-example/response-fields.asciidoc[]
|
||||
include::{generated}/notes-list-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/notes-list-example/curl-request.asciidoc[]
|
||||
include::{generated}/notes-list-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/notes-list-example/http-response.asciidoc[]
|
||||
include::{generated}/notes-list-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -147,15 +147,15 @@ A `POST` request is used to create a note
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{generated}/notes-create-example/request-fields.asciidoc[]
|
||||
include::{generated}/notes-create-example/request-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/notes-create-example/curl-request.asciidoc[]
|
||||
include::{generated}/notes-create-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/notes-create-example/http-response.asciidoc[]
|
||||
include::{generated}/notes-create-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -173,15 +173,15 @@ A `GET` request will list all of the service's tags.
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/tags-list-example/response-fields.asciidoc[]
|
||||
include::{generated}/tags-list-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tags-list-example/curl-request.asciidoc[]
|
||||
include::{generated}/tags-list-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tags-list-example/http-response.asciidoc[]
|
||||
include::{generated}/tags-list-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -192,15 +192,15 @@ A `POST` request is used to create a note
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{generated}/tags-create-example/request-fields.asciidoc[]
|
||||
include::{generated}/tags-create-example/request-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tags-create-example/curl-request.asciidoc[]
|
||||
include::{generated}/tags-create-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tags-create-example/http-response.asciidoc[]
|
||||
include::{generated}/tags-create-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -214,7 +214,7 @@ The Note resource is used to retrieve, update, and delete individual notes
|
||||
[[resources-note-links]]
|
||||
=== Links
|
||||
|
||||
include::{generated}/note-get-example/links.asciidoc[]
|
||||
include::{generated}/note-get-example/links.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -225,15 +225,15 @@ A `GET` request will retrieve the details of a note
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/note-get-example/response-fields.asciidoc[]
|
||||
include::{generated}/note-get-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/note-get-example/curl-request.asciidoc[]
|
||||
include::{generated}/note-get-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/note-get-example/http-response.asciidoc[]
|
||||
include::{generated}/note-get-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -244,17 +244,18 @@ A `PATCH` request is used to update a note
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{generated}/note-update-example/request-fields.asciidoc[]
|
||||
include::{generated}/note-update-example/request-fields.adoc[]
|
||||
|
||||
To leave an attribute of a note unchanged, any of the above may be omitted from the request.
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/note-update-example/curl-request.asciidoc[]
|
||||
include::{generated}/note-update-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/note-update-example/http-response.asciidoc[]
|
||||
include::{generated}/note-update-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-tag]]
|
||||
@@ -267,7 +268,7 @@ The Tag resource is used to retrieve, update, and delete individual tags
|
||||
[[resources-tag-links]]
|
||||
=== Links
|
||||
|
||||
include::{generated}/tag-get-example/links.asciidoc[]
|
||||
include:{{generated}/tag-get-example/links.adoc
|
||||
|
||||
|
||||
|
||||
@@ -278,15 +279,15 @@ A `GET` request will retrieve the details of a tag
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/tag-get-example/response-fields.asciidoc[]
|
||||
include::{generated}/tag-get-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tag-get-example/curl-request.asciidoc[]
|
||||
include::{generated}/tag-get-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tag-get-example/http-response.asciidoc[]
|
||||
include::{generated}/tag-get-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -297,12 +298,12 @@ A `PATCH` request is used to update a tag
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{generated}/tag-update-example/request-fields.asciidoc[]
|
||||
include::{generated}/tag-update-example/request-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tag-update-example/curl-request.asciidoc[]
|
||||
include::{generated}/tag-update-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tag-update-example/http-response.asciidoc[]
|
||||
include::{generated}/tag-update-example/http-response.adoc[]
|
||||
@@ -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/curl-request.asciidoc[]
|
||||
include::{generated}/index/1/curl-request.adoc[]
|
||||
|
||||
This request should yield the following response in the
|
||||
http://stateless.co/hal_specification.html[Hypertext Application Language (HAL)] format:
|
||||
|
||||
include::{generated}/index/1/http-response.asciidoc[]
|
||||
include::{generated}/index/1/http-response.adoc[]
|
||||
|
||||
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/http-response.asciidoc[]
|
||||
include::{generated}/index/1/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/1/curl-request.adoc[]
|
||||
|
||||
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/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/1/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/2/curl-request.adoc[]
|
||||
|
||||
This request will produce a response with the note's details in its body:
|
||||
|
||||
include::{generated}/creating-a-note/2/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/2/http-response.adoc[]
|
||||
|
||||
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/http-response.asciidoc[]
|
||||
include::{generated}/index/1/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/3/curl-request.adoc[]
|
||||
|
||||
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/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/3/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/4/curl-request.adoc[]
|
||||
|
||||
This request will produce a response with the tag's details in its body:
|
||||
|
||||
include::{generated}/creating-a-note/4/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/4/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -132,25 +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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/5/curl-request.adoc[]
|
||||
|
||||
Once again, the response's `Location` header tells us the URI of the newly created note:
|
||||
|
||||
include::{generated}/creating-a-note/5/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/5/http-response.adoc[]
|
||||
|
||||
As before, a `GET` request executed against this URI will retrieve the note's details:
|
||||
|
||||
include::{generated}/creating-a-note/6/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/6/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/6/curl-request.adoc[]
|
||||
include::{generated}/creating-a-note/6/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/7/curl-request.adoc[]
|
||||
|
||||
The response embeds information about the tag that we've just associated with the note:
|
||||
|
||||
include::{generated}/creating-a-note/7/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/7/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -160,18 +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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/8/curl-request.adoc[]
|
||||
|
||||
This request should produce a `204 No Content` response:
|
||||
|
||||
include::{generated}/creating-a-note/8/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/8/http-response.adoc[]
|
||||
|
||||
When we first created this note, we noted the tags link included in its details:
|
||||
|
||||
include::{generated}/creating-a-note/2/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/2/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/9/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/9/curl-request.adoc[]
|
||||
include::{generated}/creating-a-note/9/http-response.adoc[]
|
||||
@@ -64,12 +64,12 @@ use of HTTP status codes.
|
||||
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:
|
||||
|
||||
include::{generated}/error-example/response-fields.asciidoc[]
|
||||
include::{generated}/error-example/response-fields.adoc
|
||||
|
||||
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/http-response.asciidoc[]
|
||||
include::{generated}/error-example/http-response.adoc[]
|
||||
|
||||
[[overview-hypermedia]]
|
||||
== Hypermedia
|
||||
@@ -99,18 +99,18 @@ A `GET` request is used to access the index
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/index-example/response-fields.asciidoc[]
|
||||
include::{generated}/index-example/response-fields.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/index-example/http-response.asciidoc[]
|
||||
include::{generated}/index-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-index-links]]
|
||||
==== Links
|
||||
|
||||
include::{generated}/index-example/links.asciidoc[]
|
||||
include::{generated}/index-example/links.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -128,15 +128,15 @@ A `GET` request will list all of the service's notes.
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/notes-list-example/response-fields.asciidoc[]
|
||||
include::{generated}/notes-list-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/notes-list-example/curl-request.asciidoc[]
|
||||
include::{generated}/notes-list-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/notes-list-example/http-response.asciidoc[]
|
||||
include::{generated}/notes-list-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -147,15 +147,15 @@ A `POST` request is used to create a note
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{generated}/notes-create-example/request-fields.asciidoc[]
|
||||
include::{generated}/notes-create-example/request-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/notes-create-example/curl-request.asciidoc[]
|
||||
include::{generated}/notes-create-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/notes-create-example/http-response.asciidoc[]
|
||||
include::{generated}/notes-create-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -173,15 +173,15 @@ A `GET` request will list all of the service's tags.
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/tags-list-example/response-fields.asciidoc[]
|
||||
include::{generated}/tags-list-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tags-list-example/curl-request.asciidoc[]
|
||||
include::{generated}/tags-list-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tags-list-example/http-response.asciidoc[]
|
||||
include::{generated}/tags-list-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -192,15 +192,15 @@ A `POST` request is used to create a note
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{generated}/tags-create-example/request-fields.asciidoc[]
|
||||
include::{generated}/tags-create-example/request-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tags-create-example/curl-request.asciidoc[]
|
||||
include::{generated}/tags-create-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tags-create-example/http-response.asciidoc[]
|
||||
include::{generated}/tags-create-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -214,7 +214,7 @@ The Note resource is used to retrieve, update, and delete individual notes
|
||||
[[resources-note-links]]
|
||||
=== Links
|
||||
|
||||
include::{generated}/note-get-example/links.asciidoc[]
|
||||
include::{generated}/note-get-example/links.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -225,15 +225,15 @@ A `GET` request will retrieve the details of a note
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/note-get-example/response-fields.asciidoc[]
|
||||
include::{generated}/note-get-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/note-get-example/curl-request.asciidoc[]
|
||||
include::{generated}/note-get-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/note-get-example/http-response.asciidoc[]
|
||||
include::{generated}/note-get-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -244,18 +244,17 @@ A `PATCH` request is used to update a note
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{generated}/note-update-example/request-fields.asciidoc[]
|
||||
include::{generated}/note-update-example/request-fields.adoc[]
|
||||
|
||||
To leave an attribute of a note unchanged, any of the above may be omitted from the request.
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/note-update-example/curl-request.asciidoc[]
|
||||
include::{generated}/note-update-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/note-update-example/http-response.asciidoc[]
|
||||
|
||||
include::{generated}/note-update-example/http-response.adoc[]
|
||||
|
||||
|
||||
[[resources-tag]]
|
||||
@@ -268,7 +267,7 @@ The Tag resource is used to retrieve, update, and delete individual tags
|
||||
[[resources-tag-links]]
|
||||
=== Links
|
||||
|
||||
include:{{generated}/tag-get-example/links.asciidoc
|
||||
include::{generated}/tag-get-example/links.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -279,15 +278,15 @@ A `GET` request will retrieve the details of a tag
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{generated}/tag-get-example/response-fields.asciidoc[]
|
||||
include::{generated}/tag-get-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tag-get-example/curl-request.asciidoc[]
|
||||
include::{generated}/tag-get-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tag-get-example/http-response.asciidoc[]
|
||||
include::{generated}/tag-get-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -298,12 +297,12 @@ A `PATCH` request is used to update a tag
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{generated}/tag-update-example/request-fields.asciidoc[]
|
||||
include::{generated}/tag-update-example/request-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{generated}/tag-update-example/curl-request.asciidoc[]
|
||||
include::{generated}/tag-update-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{generated}/tag-update-example/http-response.asciidoc[]
|
||||
include::{generated}/tag-update-example/http-response.adoc[]
|
||||
@@ -42,11 +42,11 @@ $ 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/curl-request.asciidoc[]
|
||||
include::{generated}/index/1/curl-request.adoc[]
|
||||
|
||||
This request should yield the following response:
|
||||
|
||||
include::{generated}/index/1/http-response.asciidoc[]
|
||||
include::{generated}/index/1/http-response.adoc[]
|
||||
|
||||
Note the `_links` in the JSON response. They are key to navigating the API.
|
||||
|
||||
@@ -58,26 +58,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/http-response.asciidoc[]
|
||||
include::{generated}/index/1/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/1/curl-request.adoc[]
|
||||
|
||||
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/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/1/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/2/curl-request.adoc[]
|
||||
|
||||
This request will produce a response with the note's details in its body:
|
||||
|
||||
include::{generated}/creating-a-note/2/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/2/http-response.adoc[]
|
||||
|
||||
Note the `note-tags` link which we'll make use of later.
|
||||
|
||||
@@ -91,26 +91,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/http-response.asciidoc[]
|
||||
include::{generated}/index/1/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/3/curl-request.adoc[]
|
||||
|
||||
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/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/3/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/4/curl-request.adoc[]
|
||||
|
||||
This request will produce a response with the tag's details in its body:
|
||||
|
||||
include::{generated}/creating-a-note/4/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/4/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -131,25 +131,25 @@ with it.
|
||||
Once again we execute a `POST` request, but this time, in an array named tags, we include
|
||||
the URI of the tag we just created:
|
||||
|
||||
include::{generated}/creating-a-note/5/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/5/curl-request.adoc[]
|
||||
|
||||
Once again, the response's `Location` header tells use the URI of the newly created note:
|
||||
|
||||
include::{generated}/creating-a-note/5/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/5/http-response.adoc[]
|
||||
|
||||
As before, a `GET` request executed against this URI will retrieve the note's details:
|
||||
|
||||
include::{generated}/creating-a-note/6/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/6/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/6/curl-request.adoc[]
|
||||
include::{generated}/creating-a-note/6/http-response.adoc[]
|
||||
|
||||
To see the note's tags, execute a `GET` request against the URI of the note's
|
||||
`note-tags` link:
|
||||
|
||||
include::{generated}/creating-a-note/7/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/7/curl-request.adoc[]
|
||||
|
||||
The response shows that, as expected, the note has a single tag:
|
||||
|
||||
include::{generated}/creating-a-note/7/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/7/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
@@ -159,18 +159,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 use the
|
||||
URI of the untagged note that we created earlier:
|
||||
|
||||
include::{generated}/creating-a-note/8/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/8/curl-request.adoc[]
|
||||
|
||||
This request should produce a `204 No Content` response:
|
||||
|
||||
include::{generated}/creating-a-note/8/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/8/http-response.adoc[]
|
||||
|
||||
When we first created this note, we noted the `note-tags` link included in its details:
|
||||
|
||||
include::{generated}/creating-a-note/2/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/2/http-response.adoc[]
|
||||
|
||||
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/curl-request.asciidoc[]
|
||||
include::{generated}/creating-a-note/9/http-response.asciidoc[]
|
||||
include::{generated}/creating-a-note/9/curl-request.adoc[]
|
||||
include::{generated}/creating-a-note/9/http-response.adoc[]
|
||||
@@ -57,7 +57,7 @@ public abstract class SnippetWritingResultHandler implements ResultHandler {
|
||||
|
||||
private Writer createWriter() throws IOException {
|
||||
File outputFile = new OutputFileResolver().resolve(this.outputDir, this.fileName
|
||||
+ ".asciidoc");
|
||||
+ ".adoc");
|
||||
|
||||
if (outputFile != null) {
|
||||
File parent = outputFile.getParentFile();
|
||||
|
||||
@@ -84,8 +84,7 @@ public class RestDocumentationIntegrationTests {
|
||||
mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
|
||||
.andExpect(status().isOk()).andDo(document("basic"));
|
||||
assertExpectedSnippetFilesExist(new File("build/generated-snippets/basic"),
|
||||
"http-request.asciidoc", "http-response.asciidoc",
|
||||
"curl-request.asciidoc");
|
||||
"http-request.adoc", "http-response.adoc", "curl-request.adoc");
|
||||
}
|
||||
|
||||
@Test
|
||||
@@ -97,8 +96,7 @@ public class RestDocumentationIntegrationTests {
|
||||
.andExpect(status().isOk()).andDo(document("{method-name}"));
|
||||
assertExpectedSnippetFilesExist(new File(
|
||||
"build/generated-snippets/parameterized-output-directory"),
|
||||
"http-request.asciidoc", "http-response.asciidoc",
|
||||
"curl-request.asciidoc");
|
||||
"http-request.adoc", "http-response.adoc", "curl-request.adoc");
|
||||
}
|
||||
|
||||
@Test
|
||||
@@ -110,23 +108,20 @@ public class RestDocumentationIntegrationTests {
|
||||
mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON)).andExpect(
|
||||
status().isOk());
|
||||
assertExpectedSnippetFilesExist(
|
||||
new File("build/generated-snippets/multi-step-1/"),
|
||||
"http-request.asciidoc", "http-response.asciidoc",
|
||||
"curl-request.asciidoc");
|
||||
new File("build/generated-snippets/multi-step-1/"), "http-request.adoc",
|
||||
"http-response.adoc", "curl-request.adoc");
|
||||
|
||||
mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON)).andExpect(
|
||||
status().isOk());
|
||||
assertExpectedSnippetFilesExist(
|
||||
new File("build/generated-snippets/multi-step-2/"),
|
||||
"http-request.asciidoc", "http-response.asciidoc",
|
||||
"curl-request.asciidoc");
|
||||
new File("build/generated-snippets/multi-step-2/"), "http-request.adoc",
|
||||
"http-response.adoc", "curl-request.adoc");
|
||||
|
||||
mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON)).andExpect(
|
||||
status().isOk());
|
||||
assertExpectedSnippetFilesExist(
|
||||
new File("build/generated-snippets/multi-step-3/"),
|
||||
"http-request.asciidoc", "http-response.asciidoc",
|
||||
"curl-request.asciidoc");
|
||||
new File("build/generated-snippets/multi-step-3/"), "http-request.adoc",
|
||||
"http-response.adoc", "curl-request.adoc");
|
||||
|
||||
}
|
||||
|
||||
|
||||
@@ -226,7 +226,7 @@ public class CurlDocumentationTests {
|
||||
private List<String> snippetLines(String snippetName, String snippetType)
|
||||
throws IOException {
|
||||
File snippetDir = new File(this.outputDir, snippetName);
|
||||
File snippetFile = new File(snippetDir, snippetType + ".asciidoc");
|
||||
File snippetFile = new File(snippetDir, snippetType + ".adoc");
|
||||
String line = null;
|
||||
List<String> lines = new ArrayList<String>();
|
||||
BufferedReader reader = new BufferedReader(new FileReader(snippetFile));
|
||||
|
||||
@@ -158,7 +158,7 @@ public class HttpDocumentationTests {
|
||||
private List<String> snippetLines(String snippetName, String snippetType)
|
||||
throws IOException {
|
||||
File snippetDir = new File(this.outputDir, snippetName);
|
||||
File snippetFile = new File(snippetDir, snippetType + ".asciidoc");
|
||||
File snippetFile = new File(snippetDir, snippetType + ".adoc");
|
||||
String line = null;
|
||||
List<String> lines = new ArrayList<String>();
|
||||
BufferedReader reader = new BufferedReader(new FileReader(snippetFile));
|
||||
|
||||
Reference in New Issue
Block a user