You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Before we accept a non-trivial patch or pull request we will need you to sign the
16
-
[contributor's license agreement (CLA)][2]. Signing the contributor's agreement does not
17
-
grant anyone commit rights to the main repository, but it does mean that we can accept
18
-
your contributions, and you will get an author credit if we do.
13
+
Before we accept a non-trivial patch or pull request we will need you to sign the [contributor's license agreement (CLA)][2].
14
+
Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do.
19
15
20
16
21
17
## Code conventions and housekeeping
22
18
23
19
None of these is essential for a pull request, but they will all help
24
20
25
-
- Make sure all new `.java` files to have a simple Javadoc class comment with at least an
26
-
`@author` tag identifying you, and preferably at least a paragraph on what the class is
27
-
for.
28
-
- Add the ASF license header comment to all new `.java` files (copy from existing files
29
-
in the project)
30
-
- Add yourself as an `@author` to the .java files that you modify substantially (more
31
-
than cosmetic changes).
21
+
- Make sure all new `.java` files to have a simple Javadoc class comment with at least an `@author` tag identifying you, and preferably at least a paragraph on what the class is for
22
+
- Add the ASF license header comment to all new `.java` files (copy from existing files in the project)
23
+
- Add yourself as an `@author` to the .java files that you modify substantially (more than cosmetic changes)
32
24
- Add some Javadocs
33
25
- Add unit tests that covers and new or modified functionality
34
-
- Whenever possible, please rebase your branch against the current main (or other
35
-
target branch in the project).
36
-
* When writing a commit message please follow [these conventions][3]. Also, if you are
37
-
fixing an existing issue please add `Fixes gh-nnn` at the end of the commit message
38
-
(where nnn is the issue number).
26
+
- Whenever possible, please rebase your branch against the current main (or other target branch in the project)
27
+
- When writing a commit message please follow [these conventions][3]
28
+
Also, if you are fixing an existing issue please add `Fixes gh-nnn` at the end of the commit message (where nnn is the issue number)
39
29
40
30
## Working with the code
41
31
42
32
### Building from source
43
33
44
-
To build the source you will need Java 8 or later. The code is built with Gradle:
34
+
To build the source you will need Java 8 or later.
35
+
The code is built with Gradle:
45
36
46
37
```
47
38
$ ./gradlew build
@@ -55,15 +46,14 @@ $ ./gradlew buildSamples
55
46
56
47
### Importing into Eclipse
57
48
58
-
The project has Gradle's Eclipse plugin applied. Eclipse project and classpath metadata
59
-
can be generated by running the `eclipse` task:
49
+
The project has Gradle's Eclipse plugin applied.
50
+
Eclipse project and classpath metadata can be generated by running the `eclipse` task:
60
51
61
52
```
62
53
$ ./gradlew eclipse
63
54
```
64
55
65
-
The project can then be imported into Eclipse using `File -> Import…` and then selecting
66
-
`General -> Existing Projects into Workspace`.
56
+
The project can then be imported into Eclipse using `File -> Import…` and then selecting `General -> Existing Projects into Workspace`.
Copy file name to clipboardExpand all lines: README.md
+9-11
Original file line number
Diff line number
Diff line change
@@ -2,22 +2,20 @@
2
2
3
3
## Overview
4
4
5
-
The primary goal of this project is to make it easy to document RESTful services by
6
-
combining content that's been hand-written using [Asciidoctor][3] with auto-generated
7
-
examples produced with the [Spring MVC Test][4] framework. The result is intended to be
8
-
an easy-to-read user guide, akin to [GitHub's API documentation][5] for example, rather
9
-
than the fully automated, dense API documentation produced by tools like [Swagger][6].
5
+
The primary goal of this project is to make it easy to document RESTful services by combining content that's been hand-written using [Asciidoctor][3] with auto-generated examples produced with the [Spring MVC Test][4] framework.
6
+
The result is intended to be an easy-to-read user guide, akin to [GitHub's API documentation][5] for example, rather than the fully automated, dense API documentation produced by tools like [Swagger][6].
10
7
11
-
For a broader introduction see the Documenting RESTful APIs presentation. Both the
12
-
[slides][7] and a [video recording][8] are available.
8
+
For a broader introduction see the Documenting RESTful APIs presentation.
9
+
Both the [slides][7] and a [video recording][8] are available.
13
10
14
11
## Learning more
15
12
16
13
To learn more about Spring REST Docs, please consult the [reference documentation][9].
17
14
18
15
## Building from source
19
16
20
-
You will need Java 8 or later to build Spring REST Docs. It is built using [Gradle][10]:
17
+
You will need Java 8 or later to build Spring REST Docs.
18
+
It is built using [Gradle][10]:
21
19
22
20
```
23
21
./gradlew build
@@ -29,9 +27,9 @@ Contributors to this project agree to uphold its [code of conduct][11].
29
27
30
28
There are several that you can contribute to Spring REST Docs:
31
29
32
-
- Open a [pull request][12]. Please see the [contributor guidelines][13] for details.
33
-
- Ask and answer questions on Stack Overflow using the [`spring-restdocs`][15] tag.
34
-
- Chat with fellow users [on Gitter][16].
30
+
- Open a [pull request][12]. Please see the [contributor guidelines][13] for details
31
+
- Ask and answer questions on Stack Overflow using the [`spring-restdocs`][15] tag
NOTE: If the port is set to the default for the configured scheme (port 80 for HTTP or
42
-
port 443 for HTTPS), it is omitted from any URIs in the generated snippets.
40
+
NOTE: If the port is set to the default for the configured scheme (port 80 for HTTP or port 443 for HTTPS), it is omitted from any URIs in the generated snippets.
43
41
44
-
TIP: To configure a request's context path, use the `contextPath` method on
45
-
`MockHttpServletRequestBuilder`.
42
+
TIP: To configure a request's context path, use the `contextPath` method on `MockHttpServletRequestBuilder`.
46
43
47
44
48
45
49
46
[[configuration-uris-rest-assured]]
50
47
==== REST Assured URI Customization
51
48
52
-
REST Assured tests a service by making actual HTTP requests. As a result, URIs must be
53
-
customized once the operation on the service has been performed but before it is
`baseUrl(String)` method on `WebTestClient.Builder`]. The following example shows how to
67
-
do so:
58
+
When using WebTestClient, the default base for URIs documented by Spring REST Docs is `http://localhost:8080`.
59
+
You can customize this base by using the {spring-framework-api}/org/springframework/test/web/reactive/server/WebTestClient.Builder.html#baseUrl-java.lang.String-[ `baseUrl(String)` method on `WebTestClient.Builder`].
TIP: When Spring REST Docs converts the content of a request or a response to a `String`,
107
-
the `charset` specified in the `Content-Type` header is used if it is available. In its
108
-
absence, the JVM's default `Charset` is used. You can configure the JVM's default
109
-
`Charset` byusing the `file.encoding` system property.
99
+
TIP: When Spring REST Docs converts the content of a request or a response to a `String`, the `charset` specified in the `Content-Type` header is used if it is available.
100
+
In its absence, the JVM's default `Charset` is used.
101
+
You can configure the JVM's default `Charset` by using the `file.encoding` system property.
110
102
111
103
112
104
113
105
[[configuration-snippet-template-format]]
114
106
=== Snippet Template Format
115
107
116
-
The default snippet template format is Asciidoctor. Markdown is also supported out of the
117
-
box. You can change the default format by using the `RestDocumentationConfigurer` API.
108
+
The default snippet template format is Asciidoctor.
109
+
Markdown is also supported out of the box.
110
+
You can change the default format by using the `RestDocumentationConfigurer` API.
118
111
The following examples show how to do so:
119
112
120
113
====
@@ -151,9 +144,8 @@ Six snippets are produced by default:
151
144
* `request-body`
152
145
* `response-body`
153
146
154
-
You can change the default snippet configuration during setup by using the
155
-
`RestDocumentationConfigurer` API. The following examples produce only the `curl-request`
156
-
snippet by default:
147
+
You can change the default snippet configuration during setup by using the `RestDocumentationConfigurer` API.
148
+
The following examples produce only the `curl-request` snippet by default:
Spring REST Docs is intended to make it easy for you to produce high-quality
5
-
documentation for your RESTful services. However, we cannot achieve that goal without
6
-
your contributions.
4
+
Spring REST Docs is intended to make it easy for you to produce high-quality documentation for your RESTful services.
5
+
However, we cannot achieve that goal without your contributions.
7
6
8
7
9
8
10
9
[[contributing-questions]]
11
10
=== Questions
12
11
13
-
You can ask questions about Spring REST Docs on https://stackoverflow.com[Stack Overflow]
14
-
by using the `spring-restdocs` tag. Similarly, we encourage you to help your fellow
15
-
Spring REST Docs users by answering questions.
12
+
You can ask questions about Spring REST Docs on https://stackoverflow.com[Stack Overflow] by using the `spring-restdocs` tag.
13
+
Similarly, we encourage you to help your fellow Spring REST Docs users by answering questions.
16
14
17
15
18
16
19
17
[[contributing-bugs]]
20
18
=== Bugs
21
19
22
-
If you believe you have found a bug, please take a moment to search the
23
-
{github}/issues?q=is%3Aissue[existing issues]. If no one else has reported the problem,
24
-
please {github}/issues/new[open a new issue] that describes the problem in detail and,
25
-
ideally, includes a test that reproduces it.
20
+
If you believe you have found a bug, please take a moment to search the {github}/issues?q=is%3Aissue[existing issues].
21
+
If no one else has reported the problem, please {github}/issues/new[open a new issue] that describes the problem in detail and, ideally, includes a test that reproduces it.
26
22
27
23
28
24
29
25
[[contributing-enhancements]]
30
26
=== Enhancements
31
27
32
-
If you would like an enhancement to be made to Spring REST Docs, pull requests are most
33
-
welcome. The source code is on {github}[GitHub]. You may want to search the
34
-
{github}/issues?q=is%3Aissue[existing issues] and {github}/pulls?q=is%3Apr[pull requests]
35
-
to see if the enhancement has already been proprosed. You may also want to
36
-
{github}/issues/new[open a new issue] to discuss a possible enhancement before work on it
37
-
begins.
28
+
If you would like an enhancement to be made to Spring REST Docs, pull requests are most welcome.
29
+
The source code is on {github}[GitHub].
30
+
You may want to search the {github}/issues?q=is%3Aissue[existing issues] and {github}/pulls?q=is%3Apr[pull requests] to see if the enhancement has already been proposed.
31
+
You may also want to {github}/issues/new[open a new issue] to discuss a possible enhancement before work on it begins.
0 commit comments