Use snake_case consistently for anchors and cross-references

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

View File

@@ -12,7 +12,7 @@ Andy Wilkinson;
[[overview]] [[overview]]
= Overview = Overview
[[overview-http-verbs]] [[overview_http_verbs]]
== HTTP verbs == HTTP verbs
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its 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 | Used to delete an existing resource
|=== |===
[[overview-http-status-codes]] [[overview_http_status_codes]]
== HTTP status codes == HTTP status codes
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its 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 | The requested resource did not exist
|=== |===
[[overview-errors]] [[overview_errors]]
== Errors == Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object 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[] include::{snippets}/error-example/http-response.adoc[]
[[overview-hypermedia]] [[overview_hypermedia]]
== Hypermedia == Hypermedia
RESTful Notes uses hypermedia and resources include links to other resources in their 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 == Index
The index provides the entry point into the service. The index provides the entry point into the service.
[[resources-index-access]] [[resources_index_access]]
=== Accessing the index === Accessing the index
A `GET` request is used to access 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 == Notes
The Notes resources is used to create and list notes The Notes resources is used to create and list notes
[[resources-notes-list]] [[resources_notes_list]]
=== Listing notes === Listing notes
A `GET` request will list all of the service's 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 === Creating a note
A `POST` request is used to create 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 == Tags
The Tags resource is used to create and list tags. The Tags resource is used to create and list tags.
[[resources-tags-list]] [[resources_tags_list]]
=== Listing tags === Listing tags
A `GET` request will list all of the service's 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 === Creating a tag
A `POST` request is used to create a note 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 == Note
The Note resource is used to retrieve, update, and delete individual notes The Note resource is used to retrieve, update, and delete individual notes
[[resources-note-links]] [[resources_note_links]]
=== Links === Links
include::{snippets}/note-get-example/links.adoc[] include::{snippets}/note-get-example/links.adoc[]
[[resources-note-retrieve]] [[resources_note_retrieve]]
=== Retrieve a note === Retrieve a note
A `GET` request will retrieve the details of 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 === Update a note
A `PATCH` request is used to 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 == Tag
The Tag resource is used to retrieve, update, and delete individual tags The Tag resource is used to retrieve, update, and delete individual tags
[[resources-tag-links]] [[resources_tag_links]]
=== Links === Links
include::{snippets}/tag-get-example/links.adoc[] include::{snippets}/tag-get-example/links.adoc[]
[[resources-tag-retrieve]] [[resources_tag_retrieve]]
=== Retrieve a tag === Retrieve a tag
A `GET` request will retrieve the details of 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 === Update a tag
A `PATCH` request is used to update a tag A `PATCH` request is used to update a tag

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 == Running the service
RESTful Notes is written using https://projects.spring.io/spring-boot[Spring Boot] which 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. 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 == Creating a note
Now that you've started the service and verified that it works, the next step is to use 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 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 == Creating a tag
To make a note easier to find, it can be associated with any number of tags. To be able 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. 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 == Tagging a note
A tag isn't particularly useful until it's been associated with one or more notes. There 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 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 === Creating a tagged note
The process is largely the same as we saw before, but this time, in addition to providing 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 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 === Tagging an existing note
An existing note can be tagged by executing a `PATCH` request against the note's URI with 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 a body that contains the array of tags to be associated with the note. We'll used the

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

View File

@@ -12,7 +12,7 @@ Andy Wilkinson;
[[overview]] [[overview]]
= Overview = Overview
[[overview-http-verbs]] [[overview_http_verbs]]
== HTTP verbs == HTTP verbs
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its 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 | Used to delete an existing resource
|=== |===
[[overview-http-status-codes]] [[overview_http_status_codes]]
== HTTP status codes == HTTP status codes
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its 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 | The requested resource did not exist
|=== |===
[[overview-headers]] [[overview_headers]]
== Headers == Headers
Every response has the following header(s): Every response has the following header(s):
include::{snippets}/headers-example/response-headers.adoc[] include::{snippets}/headers-example/response-headers.adoc[]
[[overview-errors]] [[overview_errors]]
== Errors == Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object 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[] include::{snippets}/error-example/http-response.adoc[]
[[overview-hypermedia]] [[overview_hypermedia]]
== Hypermedia == Hypermedia
RESTful Notes uses hypermedia and resources include links to other resources in their 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 == Index
The index provides the entry point into the service. The index provides the entry point into the service.
[[resources-index-access]] [[resources_index_access]]
=== Accessing the index === Accessing the index
A `GET` request is used to access 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 == Notes
The Notes resources is used to create and list notes The Notes resources is used to create and list notes
[[resources-notes-list]] [[resources_notes_list]]
=== Listing notes === Listing notes
A `GET` request will list all of the service's 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 === Creating a note
A `POST` request is used to create 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 == Tags
The Tags resource is used to create and list tags. The Tags resource is used to create and list tags.
[[resources-tags-list]] [[resources_tags_list]]
=== Listing tags === Listing tags
A `GET` request will list all of the service's 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 === Creating a tag
A `POST` request is used to create a note 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 == Note
The Note resource is used to retrieve, update, and delete individual notes The Note resource is used to retrieve, update, and delete individual notes
[[resources-note-links]] [[resources_note_links]]
=== Links === Links
include::{snippets}/note-get-example/links.adoc[] include::{snippets}/note-get-example/links.adoc[]
[[resources-note-retrieve]] [[resources_note_retrieve]]
=== Retrieve a note === Retrieve a note
A `GET` request will retrieve the details of 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 === Update a note
A `PATCH` request is used to 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 == Tag
The Tag resource is used to retrieve, update, and delete individual tags The Tag resource is used to retrieve, update, and delete individual tags
[[resources-tag-links]] [[resources_tag_links]]
=== Links === Links
include::{snippets}/tag-get-example/links.adoc[] include::{snippets}/tag-get-example/links.adoc[]
[[resources-tag-retrieve]] [[resources_tag_retrieve]]
=== Retrieve a tag === Retrieve a tag
A `GET` request will retrieve the details of 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 === Update a tag
A `PATCH` request is used to update a tag A `PATCH` request is used to update a tag

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 == Running the service
RESTful Notes is written using https://projects.spring.io/spring-boot[Spring Boot] which 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. 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 == Creating a note
Now that you've started the service and verified that it works, the next step is to use 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 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 == Creating a tag
To make a note easier to find, it can be associated with any number of tags. To be able 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. 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 == Tagging a note
A tag isn't particularly useful until it's been associated with one or more notes. There 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 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 === Creating a tagged note
The process is largely the same as we saw before, but this time, in addition to providing 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 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 === Tagging an existing note
An existing note can be tagged by executing a `PATCH` request against the note's URI with 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 a body that contains the array of tags to be associated with the note. We'll use the

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