diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..85da04c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,29 @@ += Contributor Code of Conduct + +As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality. + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery +* Personal attacks +* Trolling or insulting/derogatory comments +* Public or private harassment +* Publishing other's private information, such as physical or electronic addresses without explicit permission +* Other unethical or unprofessional conduct + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. +Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team. + +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a project maintainer at spring-code-of-conduct@pivotal.io. +All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. +Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident. + +This Code of Conduct is adapted from the +https://contributor-covenant.org[Contributor Covenant], version 1.3.0, available at +https://contributor-covenant.org/version/1/3/0/[contributor-covenant.org/version/1/3/0/] diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index b8dfcb9..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,46 +0,0 @@ -# Contributor Code of Conduct - -As contributors and maintainers of this project, and in the interest of fostering an open -and welcoming community, we pledge to respect all people who contribute through reporting -issues, posting feature requests, updating documentation, submitting pull requests or -patches, and other activities. - -We are committed to making participation in this project a harassment-free experience for -everyone, regardless of level of experience, gender, gender identity and expression, -sexual orientation, disability, personal appearance, body size, race, ethnicity, age, -religion, or nationality. - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery -* Personal attacks -* Trolling or insulting/derogatory comments -* Public or private harassment -* Publishing other's private information, such as physical or electronic addresses, - without explicit permission -* Other unethical or unprofessional conduct - -Project maintainers have the right and responsibility to remove, edit, or reject comments, -commits, code, wiki edits, issues, and other contributions that are not aligned to this -Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors -that they deem inappropriate, threatening, offensive, or harmful. - -By adopting this Code of Conduct, project maintainers commit themselves to fairly and -consistently applying these principles to every aspect of managing this project. Project -maintainers who do not follow or enforce the Code of Conduct may be permanently removed -from the project team. - -This Code of Conduct applies both within project spaces and in public spaces when an -individual is representing the project or its community. - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by -contacting a project maintainer at spring-code-of-conduct@pivotal.io. All complaints will -be reviewed and investigated and will result in a response that is deemed necessary and -appropriate to the circumstances. Maintainers are obligated to maintain confidentiality -with regard to the reporter of an incident. - -This Code of Conduct is adapted from the [Contributor Covenant][1], version 1.3.0, available -at [contributor-covenant.org/version/1/3/0/][2]. - -[1]: https://contributor-covenant.org -[2]: https://contributor-covenant.org/version/1/3/0/ \ No newline at end of file diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..529d6f6 --- /dev/null +++ b/README.adoc @@ -0,0 +1,78 @@ += Spring REST Docs Samples + + + +== Overview +This repository contains a number of samples for https://github.com/spring-projects/spring-restdocs[Spring REST Docs] built using Spring Boot. + + + +=== MockMvc + +|=== +| Sample | Build System | Description + +| link:restful-notes-spring-data-rest[restful-notes-spring-data-rest] +| Maven +| Demonstrates the creation of a getting started guide and an API guide for a service implemented with https://spring.io/projects/spring-data-rest/[Spring Data REST]. + +| link:restful-notes-spring-hateoas[restful-notes-spring-hateoas] +| Gradle +| Demonstrates the creation of a getting started guide and an API guide for a service implemented with https://spring.io/projects/spring-hateoas/[Spring HATEOAS]. + +|=== + + + +=== WebTestClient + +|=== +| Sample | Build System | Description + +| link:web-test-client[web-test-client] +| Gradle +| Demonstrates the use of Spring REST Docs with Spring WebFlux’s WebTestClient. + +|=== + + + +=== REST Assured + +|=== +| Sample | Build System | Description + +| link:rest-assured[rest-assured] +| Gradle +| Demonstrates the use of Spring REST Docs with https://rest-assured.io[REST Assured]. + +|=== + + + +=== Advanced + +|=== +| Sample | Build System | Description + +| link:restful-notes-slate[restful-notes-slate] +| Gradle +| Demonstrates the use of Spring REST Docs with Markdown and https://github.com/slatedocs/slate[Slate]. + +| link:testng[testng] +| Gradle +| Demonstrates the use of Spring REST Docs with https://testng.org/doc/[TestNG]. + +|=== + + + +== Contributing + +Contributors to this repository agree to uphold its link:CODE_OF_CONDUCT.adoc[code of conduct]. + + + +== Licence + +The Spring REST Docs Samples are open source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license]. diff --git a/README.md b/README.md deleted file mode 100644 index e5b9c69..0000000 --- a/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Spring REST Docs Samples - -## Overview - -This repository contains a number of samples for [Spring REST Docs][1]. -Each sample is a standalone project in a subdirectory of this repository. -They are built using Spring Boot. - -### MockMvc - -| Sample | Build System | Description | -| ----------------------------------- | ------------ | ----------- | -| [restful-notes-spring-data-rest][2] | Maven | Demonstrates the creation of a getting started guide and an API guide for a service implemented with [Spring Data REST][3]. | -| [restful-notes-spring-hateoas][4] | Gradle | Demonstrates the creation of a getting started guide and an API guide for a service implemented with [Spring HATEOAS][5]. | - -### WebTestClient - -| Sample | Build System | Description | -| ---------------------| ------------ | ----------- | -| [web-test-client][6] | Gradle | Demonstrates the use of Spring REST Docs with Spring WebFlux’s WebTestClient. | - -### REST Assured - -| Sample | Build System | Description | -| ------------------| ------------ | ----------- | -| [rest-assured][7] | Gradle | Demonstrates the use of Spring REST Docs with [REST Assured][8]. | - -### Advanced - -| Sample | Build System | Description | -| -------------------------| ------------ | ----------- | -| [restful-notes-slate][9] | Gradle | Demonstrates the use of Spring REST Docs with Markdown and [Slate][10]. | -| [testng][11] | Grade | Demonstrates the use of Spring REST Docs with [TestNG][12]. | - -## Contributing - -Contributors to this repository agree to uphold its [code of conduct][13]. - -## Licence - -The Spring REST Docs Samples are open source software released under the [Apache 2.0 license][14]. - -[1]: https://github.com/spring-projects/spring-restdocs -[2]: restful-notes-spring-data-rest -[3]: https://spring.io/projects/spring-data-rest/ -[4]: restful-notes-spring-hateoas -[5]: https://spring.io/projects/spring-hateoas/ -[6]: restful-notes-slate -[7]: rest-assured -[8]: https://rest-assured.io -[9]: restful-notes-slate -[10]: https://github.com/slatedocs/slate -[11]: testng -[12]: https://testng.org/doc/ -[13]: CODE_OF_CONDUCT.md -[14]: https://www.apache.org/licenses/LICENSE-2.0.html diff --git a/rest-assured/README.md b/rest-assured/README.adoc similarity index 59% rename from rest-assured/README.md rename to rest-assured/README.adoc index 733f2a6..b931897 100644 --- a/rest-assured/README.md +++ b/rest-assured/README.adoc @@ -1,17 +1,18 @@ -# REST Assured Sample -A basic application that demonstrates using Spring REST Docs with [REST Assured][1]. += REST Assured Sample + +A basic application that demonstrates using Spring REST Docs with https://rest-assured.io[REST Assured]. -## Building and Running the Sample -You will need Java 17 to build and run the sample. -It is build using Gradle: +== Building and Running the Sample -``` +You will need Java 17 to build the sample. +It is built using Gradle: + +[source] +---- ./gradlew build -``` +---- As part of the build, a file named `build/docs/asciidoc/index.html` is created. It is produced using Asciidoctor and includes snippets generated by the sample's tests using Spring REST Docs. - -[1]: https://rest-assured.io \ No newline at end of file diff --git a/restful-notes-slate/README.adoc b/restful-notes-slate/README.adoc new file mode 100644 index 0000000..9838e85 --- /dev/null +++ b/restful-notes-slate/README.adoc @@ -0,0 +1,25 @@ += RESTful Notes Slate Sample + +This sample demonstrates how to document a RESTful API using Spring REST Docs and https://github.com/slatedocs/slate[Slate]. +The sample can be built with Gradle, but requires Ruby and the `bundler` gem to be installed. + + + +== Building the Sample + +You will need Java 17 to build the sample. +It is built using Gradle: + +[source] +---- +./gradlew build +open build/docs/api-guide.html +---- + + + +== Details + +The bulk of the documentation is written in Markdown in the file named link:slate/source/api-guide.html.md.erb[`api-guide.html.md.erb`] in the `slate/source` directory. +When the documentation is built, snippets generated by Spring REST Docs in the link:src/test/java/com/example/notes/ApiDocumentation.java[ApiDocumentation] tests are incorporated into this documentation by https://ruby-doc.org/stdlib-2.7.1/libdoc/erb/rdoc/ERB.html[ERB]. +The combined Markdown document is then turned into HTML. diff --git a/restful-notes-slate/README.md b/restful-notes-slate/README.md deleted file mode 100644 index 4e4ed16..0000000 --- a/restful-notes-slate/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# RESTful Notes Slate Sample - -This sample shows how to document a RESTful API using Spring REST Docs and [Slate][1]. -The sample can be built with Gradle, but requires Ruby and the `bundler` gem to be installed. - -## Quickstart - -``` -./gradlew build -open build/docs/api-guide.html -``` - -## Details - -The bulk of the documentation is written in Markdown in the file named [slate/source/api-guide.md.erb][2]. -When the documentation is built, snippets generated by Spring REST Docs in the [ApiDocumentation][3] tests are incorporated into this documentation by [ERB][4]. -The combined Markdown document is then turned into HTML. - -[1]: https://github.com/slatedocs/slate -[2]: slate/source/api-guide.html.md.erb -[3]: src/test/java/com/example/notes/ApiDocumentation.java -[4]: https://ruby-doc.org/stdlib-2.7.1/libdoc/erb/rdoc/ERB.html \ No newline at end of file diff --git a/restful-notes-spring-data-rest/README.md b/restful-notes-spring-data-rest/README.adoc similarity index 64% rename from restful-notes-spring-data-rest/README.md rename to restful-notes-spring-data-rest/README.adoc index 8b705df..d513a50 100644 --- a/restful-notes-spring-data-rest/README.md +++ b/restful-notes-spring-data-rest/README.adoc @@ -1,17 +1,20 @@ -# Restful Notes Spring Data REST Sample += Restful Notes Spring Data REST Sample + A RESTful web service for creating and storing notes. It uses hypermedia to describe the relationships between resources and to allow navigation between them. -Demonstrates using Spring REST Docs with MockMvc and Spring Data REST. +Demonstrates using Spring REST Docs with MockMvc and https://spring.io/projects/spring-data-rest/[Spring Data REST]. -## Building and Running the Sample -You will need Java 17 to build and run the sample. +== Building the Sample + +You will need Java 17 to build the sample. It is built using Maven: -``` +[source] +---- ./mvnw verify -``` +---- As part of the build, files named `build/docs/asciidoc/api-guide.html` and `build/docs/asciidoc/getting-started-guide.html` are created. They are produced using Asciidoctor and include snippets generated by the sample's tests using Spring REST Docs. diff --git a/restful-notes-spring-hateoas/README.md b/restful-notes-spring-hateoas/README.adoc similarity index 61% rename from restful-notes-spring-hateoas/README.md rename to restful-notes-spring-hateoas/README.adoc index 3a8b985..a9bc3ba 100644 --- a/restful-notes-spring-hateoas/README.md +++ b/restful-notes-spring-hateoas/README.adoc @@ -1,17 +1,20 @@ -# Restful Notes Spring Hateoas Sample += Restful Notes Spring Hateoas Sample + A RESTful web service for creating and storing notes. It uses hypermedia to describe the relationships between resources and to allow navigation between them. -Demonstrates using Spring REST Docs with MockMvc and Spring HATEOAS. +Demonstrates using Spring REST Docs with MockMvc and https://spring.io/projects/spring-hateoas/[Spring HATEOAS]. -## Building and Running the Sample -You will need Java 17 to build and run the sample. -It is build using Gradle: +== Building the Sample -``` +You will need Java 17 to build the sample. +It is built using Gradle: + +[source] +---- ./gradlew build -``` +---- As part of the build, files named `build/docs/asciidoc/api-guide.html` and `build/docs/asciidoc/getting-started-guide.html` are created. They are produced using Asciidoctor and include snippets generated by the sample's tests using Spring REST Docs. diff --git a/testng/README.md b/testng/README.adoc similarity index 59% rename from testng/README.md rename to testng/README.adoc index a253f6b..940a563 100644 --- a/testng/README.md +++ b/testng/README.adoc @@ -1,17 +1,18 @@ -# REST Assured Sample -A basic application that demonstrates using Spring REST Docs with [TestNG][1]. += TestNG Sample + +A basic application that demonstrates using Spring REST Docs with https://testng.org/doc/[TestNG]. -## Building and Running the Sample -You will need Java 17 to build and run the sample. -It is build using Gradle: +== Building the Sample -``` +You will need Java 17 to build the sample. +It is built using Gradle: + +[source] +---- ./gradlew build -``` +---- As part of the build, a file named `build/docs/asciidoc/index.html` is created. It is produced using Asciidoctor and includes snippets generated by the sample's tests using Spring REST Docs. - -[1]: https://testng.org/doc/ diff --git a/web-test-client/README.md b/web-test-client/README.adoc similarity index 68% rename from web-test-client/README.md rename to web-test-client/README.adoc index 8bf908f..19b5829 100644 --- a/web-test-client/README.md +++ b/web-test-client/README.adoc @@ -1,15 +1,18 @@ -# REST Assured Sample += WebTestClient Sample + A basic application that demonstrates using Spring REST Docs with Spring WebFlux's `WebTestClient`. -## Building and Running the Sample -You will need Java 17 to build and run the sample. -It is build using Gradle: +== Building the Sample -``` +You will need Java 17 to build the sample. +It is built using Gradle: + +[source] +---- ./gradlew build -``` +---- As part of the build, a file named `build/docs/asciidoc/index.html` is created. It is produced using Asciidoctor and includes snippets generated by the sample's tests using Spring REST Docs.