From e2e61dff53387d813c2fecb5fa583bc63d0d525c Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Fri, 27 Mar 2020 15:44:59 +0000 Subject: [PATCH] Use snake_case consistently for anchors and cross-references Closes gh-674 --- .../src/main/asciidoc/api-guide.adoc | 40 +++++++++--------- .../main/asciidoc/getting-started-guide.adoc | 12 +++--- .../com/example/notes/ApiDocumentation.java | 30 ++++++------- .../src/docs/asciidoc/api-guide.adoc | 42 +++++++++---------- .../docs/asciidoc/getting-started-guide.adoc | 12 +++--- .../com/example/notes/ApiDocumentation.java | 24 +++++------ 6 files changed, 80 insertions(+), 80 deletions(-) diff --git a/samples/rest-notes-spring-data-rest/src/main/asciidoc/api-guide.adoc b/samples/rest-notes-spring-data-rest/src/main/asciidoc/api-guide.adoc index beed99d1..8cb81784 100644 --- a/samples/rest-notes-spring-data-rest/src/main/asciidoc/api-guide.adoc +++ b/samples/rest-notes-spring-data-rest/src/main/asciidoc/api-guide.adoc @@ -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 diff --git a/samples/rest-notes-spring-data-rest/src/main/asciidoc/getting-started-guide.adoc b/samples/rest-notes-spring-data-rest/src/main/asciidoc/getting-started-guide.adoc index f794201f..b9ab9136 100644 --- a/samples/rest-notes-spring-data-rest/src/main/asciidoc/getting-started-guide.adoc +++ b/samples/rest-notes-spring-data-rest/src/main/asciidoc/getting-started-guide.adoc @@ -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 diff --git a/samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java b/samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java index 4c65f7b0..bbcc9a3f 100644 --- a/samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java +++ b/samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java @@ -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 <>"), - linkWithRel("tags").description("The <>"), + linkWithRel("notes").description("The <>"), + linkWithRel("tags").description("The <>"), linkWithRel("profile").description("The ALPS profile for the service")), responseFields( - subsectionWithPath("_links").description("<> to other resources")))); + subsectionWithPath("_links").description("<> 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 <>"), - subsectionWithPath("_links").description("<> to other resources")))); + subsectionWithPath("_embedded.notes").description("An array of <>"), + subsectionWithPath("_links").description("<> 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 <>"), - linkWithRel("note").description("This <>"), + linkWithRel("self").description("Canonical link for this <>"), + linkWithRel("note").description("This <>"), 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("<> to other resources")))); + subsectionWithPath("_links").description("<> 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 <>"), - subsectionWithPath("_links").description("<> to other resources")))); + subsectionWithPath("_embedded.tags").description("An array of <>"), + subsectionWithPath("_links").description("<> 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 <>"), - linkWithRel("tag").description("This <>"), - linkWithRel("notes").description("The <> that have this tag")), + linkWithRel("self").description("Canonical link for this <>"), + linkWithRel("tag").description("This <>"), + linkWithRel("notes").description("The notes that have this tag")), responseFields( fieldWithPath("name").description("The name of the tag"), - subsectionWithPath("_links").description("<> to other resources")))); + subsectionWithPath("_links").description("<> to other resources")))); } @Test diff --git a/samples/rest-notes-spring-hateoas/src/docs/asciidoc/api-guide.adoc b/samples/rest-notes-spring-hateoas/src/docs/asciidoc/api-guide.adoc index 27b6db58..90745896 100644 --- a/samples/rest-notes-spring-hateoas/src/docs/asciidoc/api-guide.adoc +++ b/samples/rest-notes-spring-hateoas/src/docs/asciidoc/api-guide.adoc @@ -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 diff --git a/samples/rest-notes-spring-hateoas/src/docs/asciidoc/getting-started-guide.adoc b/samples/rest-notes-spring-hateoas/src/docs/asciidoc/getting-started-guide.adoc index 788508f3..7e8346ac 100644 --- a/samples/rest-notes-spring-hateoas/src/docs/asciidoc/getting-started-guide.adoc +++ b/samples/rest-notes-spring-hateoas/src/docs/asciidoc/getting-started-guide.adoc @@ -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 diff --git a/samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java b/samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java index 78ed5974..17cebdb1 100644 --- a/samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java +++ b/samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java @@ -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 <>"), - linkWithRel("tags").description("The <>")), + linkWithRel("notes").description("The <>"), + linkWithRel("tags").description("The <>")), responseFields( - subsectionWithPath("_links").description("<> to other resources")))); + subsectionWithPath("_links").description("<> 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 <>")))); + subsectionWithPath("_embedded.notes").description("An array of <>")))); } @Test @@ -223,12 +223,12 @@ public class ApiDocumentation { .andExpect(jsonPath("_links.note-tags", is(notNullValue()))) .andDo(this.documentationHandler.document( links( - linkWithRel("self").description("This <>"), - linkWithRel("note-tags").description("This note's <>")), + linkWithRel("self").description("This <>"), + linkWithRel("note-tags").description("This note's <>")), responseFields( fieldWithPath("title").description("The title of the note"), fieldWithPath("body").description("The body of the note"), - subsectionWithPath("_links").description("<> to other resources")))); + subsectionWithPath("_links").description("<> 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 <>")))); + subsectionWithPath("_embedded.tags").description("An array of <>")))); } @Test @@ -339,11 +339,11 @@ public class ApiDocumentation { .andExpect(jsonPath("name", is(tag.get("name")))) .andDo(this.documentationHandler.document( links( - linkWithRel("self").description("This <>"), - linkWithRel("tagged-notes").description("The <> that have this tag")), + linkWithRel("self").description("This <>"), + linkWithRel("tagged-notes").description("The <> that have this tag")), responseFields( fieldWithPath("name").description("The name of the tag"), - subsectionWithPath("_links").description("<> to other resources")))); + subsectionWithPath("_links").description("<> to other resources")))); } @Test