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

Use Asciidoctor for READMEs and related files

Browse Source
This commit is contained in:
Andy Wilkinson
2022-07-26 13:47:44 +01:00
parent 3456909fe7
commit 0cbcb448d5
11 changed files with 180 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
CODE_OF_CONDUCT.adoc Normal file
View File

@@ -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/]

46
CODE_OF_CONDUCT.md
View File

@@ -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/

78
README.adoc Normal file
View File

@@ -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].

56
README.md
View File

@@ -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

19
rest-assured/README.md → rest-assured/README.adoc
View File

@@ -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

25
restful-notes-slate/README.adoc Normal file
View File

@@ -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.

22
restful-notes-slate/README.md
View File

@@ -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

15
restful-notes-spring-data-rest/README.md → restful-notes-spring-data-rest/README.adoc
View File

@@ -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.

17
restful-notes-spring-hateoas/README.md → restful-notes-spring-hateoas/README.adoc
View File

@@ -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.

19
testng/README.md → testng/README.adoc
View File

@@ -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/

15
web-test-client/README.md → web-test-client/README.adoc
View File

@@ -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.