Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Use snake_case consistently for anchors and cross-references

Browse Source 
Closes gh-674
This commit is contained in:
Andy Wilkinson
2020-03-27 15:44:59 +00:00
parent 1ee96bbb76
commit e2e61dff53
6 changed files with 80 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
samples/rest-notes-spring-data-rest/src/main/asciidoc/api-guide.adoc
View File

@@ -12,7 +12,7 @@ Andy Wilkinson;
[[overview]]
= Overview
[[overview-http-verbs]]
[[overview_http_verbs]]
== HTTP verbs
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
@@ -34,7 +34,7 @@ use of HTTP verbs.
| Used to delete an existing resource
|===
[[overview-http-status-codes]]
[[overview_http_status_codes]]
== HTTP status codes
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
@@ -60,7 +60,7 @@ use of HTTP status codes.
| The requested resource did not exist
|===
[[overview-errors]]
[[overview_errors]]
== Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object
@@ -73,7 +73,7 @@ For example, a request that attempts to apply a non-existent tag to a note will
include::{snippets}/error-example/http-response.adoc[]
[[overview-hypermedia]]
[[overview_hypermedia]]
== Hypermedia
RESTful Notes uses hypermedia and resources include links to other resources in their
@@ -87,14 +87,14 @@ links to navigate from resource to resource.
[[resources-index]]
[[resources_index]]
== Index
The index provides the entry point into the service.
[[resources-index-access]]
[[resources_index_access]]
=== Accessing the index
A `GET` request is used to access the index
@@ -103,14 +103,14 @@ operation::index-example[snippets='response-fields,http-response,links']
[[resources-notes]]
[[resources_notes]]
== Notes
The Notes resources is used to create and list notes
[[resources-notes-list]]
[[resources_notes_list]]
=== Listing notes
A `GET` request will list all of the service's notes.
@@ -119,7 +119,7 @@ operation::notes-list-example[snippets='response-fields,curl-request,http-respon
[[resources-notes-create]]
[[resources_notes_create]]
=== Creating a note
A `POST` request is used to create a note.
@@ -128,14 +128,14 @@ operation::notes-create-example[snippets='request-fields,curl-request,http-respo
[[resources-tags]]
[[resources_tags]]
== Tags
The Tags resource is used to create and list tags.
[[resources-tags-list]]
[[resources_tags_list]]
=== Listing tags
A `GET` request will list all of the service's tags.
@@ -144,7 +144,7 @@ operation::tags-list-example[snippets='response-fields,curl-request,http-respons
[[resources-tags-create]]
[[resources_tags_create]]
=== Creating a tag
A `POST` request is used to create a note
@@ -153,21 +153,21 @@ operation::tags-create-example[snippets='request-fields,curl-request,http-respon
[[resources-note]]
[[resources_note]]
== Note
The Note resource is used to retrieve, update, and delete individual notes
[[resources-note-links]]
[[resources_note_links]]
=== Links
include::{snippets}/note-get-example/links.adoc[]
[[resources-note-retrieve]]
[[resources_note_retrieve]]
=== Retrieve a note
A `GET` request will retrieve the details of a note
@@ -176,7 +176,7 @@ operation::note-get-example[snippets='response-fields,curl-request,http-response
[[resources-note-update]]
[[resources_note_update]]
=== Update a note
A `PATCH` request is used to update a note
@@ -197,21 +197,21 @@ include::{snippets}/note-update-example/http-response.adoc[]
[[resources-tag]]
[[resources_tag]]
== Tag
The Tag resource is used to retrieve, update, and delete individual tags
[[resources-tag-links]]
[[resources_tag_links]]
=== Links
include::{snippets}/tag-get-example/links.adoc[]
[[resources-tag-retrieve]]
[[resources_tag_retrieve]]
=== Retrieve a tag
A `GET` request will retrieve the details of a tag
@@ -220,7 +220,7 @@ operation::tag-get-example[snippets='response-fields,curl-request,http-response'
[[resources-tag-update]]
[[resources_tag_update]]
=== Update a tag
A `PATCH` request is used to update a tag

12
samples/rest-notes-spring-data-rest/src/main/asciidoc/getting-started-guide.adoc
View File

@@ -15,7 +15,7 @@ to describe the relationships between resources and to allow navigation between
[[getting-started-running-the-service]]
[[getting_started_running_the_service]]
== Running the service
RESTful Notes is written using https://projects.spring.io/spring-boot[Spring Boot] which
makes it easy to get it up and running so that you can start exploring the REST API.
@@ -51,7 +51,7 @@ Note the `_links` in the JSON response. They are key to navigating the API.
[[getting-started-creating-a-note]]
[[getting_started_creating_a_note]]
== Creating a note
Now that you've started the service and verified that it works, the next step is to use
it to create a new note. As you saw above, the URI for working with notes is included as
@@ -82,7 +82,7 @@ Note the `tags` link which we'll make use of later.
[[getting-started-creating-a-tag]]
[[getting_started_creating_a_tag]]
== Creating a tag
To make a note easier to find, it can be associated with any number of tags. To be able
to tag a note, you must first create the tag.
@@ -113,7 +113,7 @@ include::{snippets}/creating-a-note/4/http-response.adoc[]
[[getting-started-tagging-a-note]]
[[getting_started_tagging_a_note]]
== Tagging a note
A tag isn't particularly useful until it's been associated with one or more notes. There
are two ways to tag a note: when the note is first created or by updating an existing
@@ -121,7 +121,7 @@ note. We'll look at both of these in turn.
[[getting-started-tagging-a-note-creating]]
[[getting_started_tagging_a_note_creating]]
=== Creating a tagged note
The process is largely the same as we saw before, but this time, in addition to providing
a title and body for the note, we'll also provide the tag that we want to be associated
@@ -152,7 +152,7 @@ include::{snippets}/creating-a-note/7/http-response.adoc[]
[[getting-started-tagging-a-note-existing]]
[[getting_started_tagging_a_note_existing]]
=== Tagging an existing note
An existing note can be tagged by executing a `PATCH` request against the note's URI with
a body that contains the array of tags to be associated with the note. We'll used the

30
samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2014-2019 the original author or authors.
* Copyright 2014-2020 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -111,11 +111,11 @@ public class ApiDocumentation {
.andExpect(status().isOk())
.andDo(document("index-example",
links(
linkWithRel("notes").description("The <<resources-notes,Notes resource>>"),
linkWithRel("tags").description("The <<resources-tags,Tags resource>>"),
linkWithRel("notes").description("The <<resources_notes,Notes resource>>"),
linkWithRel("tags").description("The <<resources_tags,Tags resource>>"),
linkWithRel("profile").description("The ALPS profile for the service")),
responseFields(
subsectionWithPath("_links").description("<<resources-index-links,Links>> to other resources"))));
subsectionWithPath("_links").description("<<resources_index_access_links,Links>> to other resources"))));
}
@@ -136,8 +136,8 @@ public class ApiDocumentation {
linkWithRel("self").description("Canonical link for this resource"),
linkWithRel("profile").description("The ALPS profile for this resource")),
responseFields(
subsectionWithPath("_embedded.notes").description("An array of <<resources-note, Note resources>>"),
subsectionWithPath("_links").description("<<resources-tags-list-links, Links>> to other resources"))));
subsectionWithPath("_embedded.notes").description("An array of <<resources_note, Note resources>>"),
subsectionWithPath("_links").description("<<resources_tags_list_links, Links>> to other resources"))));
}
@Test
@@ -201,13 +201,13 @@ public class ApiDocumentation {
.andDo(print())
.andDo(document("note-get-example",
links(
linkWithRel("self").description("Canonical link for this <<resources-note,note>>"),
linkWithRel("note").description("This <<resources-note,note>>"),
linkWithRel("self").description("Canonical link for this <<resources_note,note>>"),
linkWithRel("note").description("This <<resources_note,note>>"),
linkWithRel("tags").description("This note's tags")),
responseFields(
fieldWithPath("title").description("The title of the note"),
fieldWithPath("body").description("The body of the note"),
subsectionWithPath("_links").description("<<resources-note-links,Links>> to other resources"))));
subsectionWithPath("_links").description("<<resources_note_links,Links>> to other resources"))));
}
@Test
@@ -226,8 +226,8 @@ public class ApiDocumentation {
linkWithRel("self").description("Canonical link for this resource"),
linkWithRel("profile").description("The ALPS profile for this resource")),
responseFields(
subsectionWithPath("_embedded.tags").description("An array of <<resources-tag,Tag resources>>"),
subsectionWithPath("_links").description("<<resources-tags-list-links, Links>> to other resources"))));
subsectionWithPath("_embedded.tags").description("An array of <<resources_tag,Tag resources>>"),
subsectionWithPath("_links").description("<<resources_tags_list_links, Links>> to other resources"))));
}
@Test
@@ -304,12 +304,12 @@ public class ApiDocumentation {
.andExpect(jsonPath("name", is(tag.get("name"))))
.andDo(document("tag-get-example",
links(
linkWithRel("self").description("Canonical link for this <<resources-tag,tag>>"),
linkWithRel("tag").description("This <<resources-tag,tag>>"),
linkWithRel("notes").description("The <<resources-tagged-notes,notes>> that have this tag")),
linkWithRel("self").description("Canonical link for this <<resources_tag,tag>>"),
linkWithRel("tag").description("This <<resources_tag,tag>>"),
linkWithRel("notes").description("The notes that have this tag")),
responseFields(
fieldWithPath("name").description("The name of the tag"),
subsectionWithPath("_links").description("<<resources-tag-links,Links>> to other resources"))));
subsectionWithPath("_links").description("<<resources_tag_links,Links>> to other resources"))));
}
@Test

42
samples/rest-notes-spring-hateoas/src/docs/asciidoc/api-guide.adoc
View File

@@ -12,7 +12,7 @@ Andy Wilkinson;
[[overview]]
= Overview
[[overview-http-verbs]]
[[overview_http_verbs]]
== HTTP verbs
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
@@ -34,7 +34,7 @@ use of HTTP verbs.
| Used to delete an existing resource
|===
[[overview-http-status-codes]]
[[overview_http_status_codes]]
== HTTP status codes
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
@@ -60,14 +60,14 @@ use of HTTP status codes.
| The requested resource did not exist
|===
[[overview-headers]]
[[overview_headers]]
== Headers
Every response has the following header(s):
include::{snippets}/headers-example/response-headers.adoc[]
[[overview-errors]]
[[overview_errors]]
== Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object
@@ -80,7 +80,7 @@ For example, a request that attempts to apply a non-existent tag to a note will
include::{snippets}/error-example/http-response.adoc[]
[[overview-hypermedia]]
[[overview_hypermedia]]
== Hypermedia
RESTful Notes uses hypermedia and resources include links to other resources in their
@@ -94,14 +94,14 @@ links to navigate from resource to resource.
[[resources-index]]
[[resources_index]]
== Index
The index provides the entry point into the service.
[[resources-index-access]]
[[resources_index_access]]
=== Accessing the index
A `GET` request is used to access the index
@@ -110,14 +110,14 @@ operation::index-example[snippets='response-fields,http-response,links']
[[resources-notes]]
[[resources_notes]]
== Notes
The Notes resources is used to create and list notes
[[resources-notes-list]]
[[resources_notes_list]]
=== Listing notes
A `GET` request will list all of the service's notes.
@@ -126,7 +126,7 @@ operation::notes-list-example[snippets='response-fields,curl-request,http-respon
[[resources-notes-create]]
[[resources_notes_create]]
=== Creating a note
A `POST` request is used to create a note.
@@ -135,14 +135,14 @@ operation::notes-create-example[snippets='request-fields,curl-request,http-respo
[[resources-tags]]
[[resources_tags]]
== Tags
The Tags resource is used to create and list tags.
[[resources-tags-list]]
[[resources_tags_list]]
=== Listing tags
A `GET` request will list all of the service's tags.
@@ -151,7 +151,7 @@ operation::tags-list-example[snippets='response-fields,curl-request,http-respons
[[resources-tags-create]]
[[resources_tags_create]]
=== Creating a tag
A `POST` request is used to create a note
@@ -160,21 +160,21 @@ operation::tags-create-example[snippets='request-fields,curl-request,http-respon
[[resources-note]]
[[resources_note]]
== Note
The Note resource is used to retrieve, update, and delete individual notes
[[resources-note-links]]
[[resources_note_links]]
=== Links
include::{snippets}/note-get-example/links.adoc[]
[[resources-note-retrieve]]
[[resources_note_retrieve]]
=== Retrieve a note
A `GET` request will retrieve the details of a note
@@ -183,7 +183,7 @@ operation::note-get-example[snippets='response-fields,curl-request,http-response
[[resources-note-update]]
[[resources_note_update]]
=== Update a note
A `PATCH` request is used to update a note
@@ -198,21 +198,21 @@ operation::note-update-example[snippets='curl-request,http-response']
[[resources-tag]]
[[resources_tag]]
== Tag
The Tag resource is used to retrieve, update, and delete individual tags
[[resources-tag-links]]
[[resources_tag_links]]
=== Links
include::{snippets}/tag-get-example/links.adoc[]
[[resources-tag-retrieve]]
[[resources_tag_retrieve]]
=== Retrieve a tag
A `GET` request will retrieve the details of a tag
@@ -221,7 +221,7 @@ operation::tag-get-example[snippets='response-fields,curl-request,http-response'
[[resources-tag-update]]
[[resources_tag_update]]
=== Update a tag
A `PATCH` request is used to update a tag

12
samples/rest-notes-spring-hateoas/src/docs/asciidoc/getting-started-guide.adoc
View File

@@ -15,7 +15,7 @@ to describe the relationships between resources and to allow navigation between
[[getting-started-running-the-service]]
[[getting_started_running_the_service]]
== Running the service
RESTful Notes is written using https://projects.spring.io/spring-boot[Spring Boot] which
makes it easy to get it up and running so that you can start exploring the REST API.
@@ -49,7 +49,7 @@ Note the `_links` in the JSON response. They are key to navigating the API.
[[getting-started-creating-a-note]]
[[getting_started_creating_a_note]]
== Creating a note
Now that you've started the service and verified that it works, the next step is to use
it to create a new note. As you saw above, the URI for working with notes is included as
@@ -80,7 +80,7 @@ Note the `note-tags` link which we'll make use of later.
[[getting-started-creating-a-tag]]
[[getting_started_creating_a_tag]]
== Creating a tag
To make a note easier to find, it can be associated with any number of tags. To be able
to tag a note, you must first create the tag.
@@ -111,7 +111,7 @@ include::{snippets}/creating-a-note/4/http-response.adoc[]
[[getting-started-tagging-a-note]]
[[getting_started_tagging_a_note]]
== Tagging a note
A tag isn't particularly useful until it's been associated with one or more notes. There
are two ways to tag a note: when the note is first created or by updating an existing
@@ -119,7 +119,7 @@ note. We'll look at both of these in turn.
[[getting-started-tagging-a-note-creating]]
[[getting_started_tagging_a_note_creating]]
=== Creating a tagged note
The process is largely the same as we saw before, but this time, in addition to providing
a title and body for the note, we'll also provide the tag that we want to be associated
@@ -150,7 +150,7 @@ include::{snippets}/creating-a-note/7/http-response.adoc[]
[[getting-started-tagging-a-note-existing]]
[[getting_started_tagging_a_note_existing]]
=== Tagging an existing note
An existing note can be tagged by executing a `PATCH` request against the note's URI with
a body that contains the array of tags to be associated with the note. We'll use the

24
samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2014-2019 the original author or authors.
* Copyright 2014-2020 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -136,10 +136,10 @@ public class ApiDocumentation {
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
links(
linkWithRel("notes").description("The <<resources-notes,Notes resource>>"),
linkWithRel("tags").description("The <<resources-tags,Tags resource>>")),
linkWithRel("notes").description("The <<resources_notes,Notes resource>>"),
linkWithRel("tags").description("The <<resources_tags,Tags resource>>")),
responseFields(
subsectionWithPath("_links").description("<<resources-index-links,Links>> to other resources"))));
subsectionWithPath("_links").description("<<resources_index_links,Links>> to other resources"))));
}
@Test
@@ -155,7 +155,7 @@ public class ApiDocumentation {
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
responseFields(
subsectionWithPath("_embedded.notes").description("An array of <<resources-note, Note resources>>"))));
subsectionWithPath("_embedded.notes").description("An array of <<resources_note, Note resources>>"))));
}
@Test
@@ -223,12 +223,12 @@ public class ApiDocumentation {
.andExpect(jsonPath("_links.note-tags", is(notNullValue())))
.andDo(this.documentationHandler.document(
links(
linkWithRel("self").description("This <<resources-note,note>>"),
linkWithRel("note-tags").description("This note's <<resources-note-tags,tags>>")),
linkWithRel("self").description("This <<resources_note,note>>"),
linkWithRel("note-tags").description("This note's <<resources_note_tags,tags>>")),
responseFields(
fieldWithPath("title").description("The title of the note"),
fieldWithPath("body").description("The body of the note"),
subsectionWithPath("_links").description("<<resources-note-links,Links>> to other resources"))));
subsectionWithPath("_links").description("<<resources_note_links,Links>> to other resources"))));
}
@@ -246,7 +246,7 @@ public class ApiDocumentation {
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
responseFields(
subsectionWithPath("_embedded.tags").description("An array of <<resources-tag,Tag resources>>"))));
subsectionWithPath("_embedded.tags").description("An array of <<resources_tag,Tag resources>>"))));
}
@Test
@@ -339,11 +339,11 @@ public class ApiDocumentation {
.andExpect(jsonPath("name", is(tag.get("name"))))
.andDo(this.documentationHandler.document(
links(
linkWithRel("self").description("This <<resources-tag,tag>>"),
linkWithRel("tagged-notes").description("The <<resources-tagged-notes,notes>> that have this tag")),
linkWithRel("self").description("This <<resources_tag,tag>>"),
linkWithRel("tagged-notes").description("The <<resources_tagged_notes,notes>> that have this tag")),
responseFields(
fieldWithPath("name").description("The name of the tag"),
subsectionWithPath("_links").description("<<resources-tag-links,Links>> to other resources"))));
subsectionWithPath("_links").description("<<resources_tag_links,Links>> to other resources"))));
}
@Test