Skip to content

Commit e8d8122

Browse files
bclozelbclozel
committed
Remove duplicate reference documentation
Now that the reference documentation has been moved to its proper toolchain, we can remove its former copy from the README file. See gh-76
1 parent 818396f commit e8d8122

File tree

1 file changed

+11
-230
lines changed

1 file changed

+11
-230
lines changed

‎README.md

Lines changed: 11 additions & 230 deletions
Original file line numberDiff line numberDiff line change
@@ -1,244 +1,25 @@
1-
# Spring GraphQL
2-
[GraphQL](https://graphql.org/) support for Spring applications with [GraphQL Java](https://github.com/graphql-java/graphql-java).
3-
4-
[![Build status](https://ci.spring.io/api/v1/teams/spring-graphql/pipelines/spring-graphql/jobs/build/badge)](https://ci.spring.io/teams/spring-graphql/pipelines/spring-graphql)
5-
6-
7-
## Getting started
8-
9-
This project is tested against Spring Boot 2.4+.
10-
11-
You can start by creating a project on https://start.spring.io and select the `spring-boot-starter-web` or `spring-boot-starter-webflux` starter,
12-
depending on the type of web application you'd like to build. Once the project is generated, you can manually add the
13-
`org.springframework.experimental:graphql-spring-boot-starter` dependency.
14-
15-
`build.gradle` snippet:
16-
```groovy
17-
dependencies {
18-
implementation 'org.springframework.experimental:graphql-spring-boot-starter:1.0.0-SNAPSHOT'
19-
20-
// Spring Web MVC starter
21-
implementation 'org.springframework.boot:spring-boot-starter-web'
22-
// OR Spring WebFlux starter
23-
implementation 'org.springframework.boot:spring-boot-starter-webflux'
24-
25-
}
26-
27-
repositories {
28-
mavenCentral()
29-
// don't forget to add spring milestone or snapshot repositories
30-
maven { url 'https://repo.spring.io/milestone' }
31-
maven { url 'https://repo.spring.io/snapshot' }
32-
}
33-
```
34-
35-
`pom.xml` snippet:
36-
```xml
37-
<dependencies>
38-
<dependency>
39-
<groupId>org.springframework.experimental</groupId>
40-
<artifactId>graphql-spring-boot-starter</artifactId>
41-
<version>1.0.0-SNAPSHOT</version>
42-
</dependency>
43-
44-
<!-- Spring Web MVC starter -->
45-
<dependency>
46-
<groupId>org.springframework.boot</groupId>
47-
<artifactId>spring-boot-starter-web</artifactId>
48-
</dependency>
49-
<!-- OR Spring WebFlux starter -->
50-
<dependency>
51-
<groupId>org.springframework.boot</groupId>
52-
<artifactId>spring-boot-starter-webflux</artifactId>
53-
</dependency>
54-
<!-- ... -->
55-
</dependencies>
56-
57-
<!-- Don't forget to add spring milestone or snapshot repositories -->
58-
<repositories>
59-
<repository>
60-
<id>spring-milestones</id>
61-
<name>Spring Milestones</name>
62-
<url>https://repo.spring.io/milestone</url>
63-
</repository>
64-
<repository>
65-
<id>spring-snapshots</id>
66-
<name>Spring Snapshots</name>
67-
<url>https://repo.spring.io/snapshot</url>
68-
<snapshots>
69-
<enabled>true</enabled>
70-
</snapshots>
71-
</repository>
72-
</repositories>
73-
```
74-
75-
You can now add a GraphQL schema in `src/main/resources/graphql/schema.graphqls` such as:
76-
77-
```
78-
type Query {
79-
people: [Person]!
80-
}
81-
82-
type Person {
83-
id: ID!
84-
name: String!
85-
}
86-
```
87-
88-
Then you should configure the data fetching process using a `RuntimeWiringCustomizer` and custom components like
89-
Spring Data repositories, `WebClient` instances for Web APIs, a `@Service` bean, etc.
90-
91-
```java
92-
@Component
93-
public class PersonDataWiring implements RuntimeWiringCustomizer {
94-
95-
private final PersonService personService;
96-
97-
public PersonDataWiring(PersonService personService) {
98-
this.personService = personService;
99-
}
100-
101-
@Override
102-
public void customize(RuntimeWiring.Builder builder) {
103-
builder.type("Query", typeWiring -> typeWiring
104-
.dataFetcher("people", env -> this.personService.findAll()));
105-
}
106-
}
107-
```
108-
109-
You can now start your application!
110-
A GraphiQL web interface is available at `http://localhost:8080/graphql` and you can use GraphQL clients
111-
to POST queries at the same location.
112-
113-
114-
## Features
1+
# Spring GraphQL [![Build status](https://ci.spring.io/api/v1/teams/spring-graphql/pipelines/spring-graphql/jobs/build/badge)](https://ci.spring.io/teams/spring-graphql/pipelines/spring-graphql)
1152

116-
### Core configuration
117-
The Spring GraphQL project offers a few configuration properties to customize your application:
118-
119-
````properties
120-
# web path to the graphql endpoint
121-
spring.graphql.path=/graphql
122-
# locations of the graphql '*.graphqls' schema files
123-
spring.graphql.schema.locations=classpath:graphql/
124-
# schema printer endpoint configuration
125-
# endpoint path is concatenated with the main path, so "/graphql/schema" by default
126-
spring.graphql.schema.printer.enabled=false
127-
spring.graphql.schema.printer.path=/schema
128-
# GraphiQL UI configuration
129-
spring.graphql.graphiql.enabled=true
130-
spring.graphql.graphiql.path=/graphiql
131-
# whether micrometer metrics should be collected for graphql queries
132-
management.metrics.graphql.autotime.enabled=true
133-
````
134-
135-
You can contribute `RuntimeWiringCustomizer` beans to the context in order to configure the runtime wiring of your GraphQL application.
136-
137-
### WebSocket support
138-
139-
This project also supports WebSocket as a transport for GraphQL requests - you can use it to build [`Subscription` queries](http://spec.graphql.org/draft/#sec-Subscription).
140-
This use case is powered by Reactor `Flux`, check out the `samples/webflux-websocket` sample application for more.
141-
142-
To enable this support, you need to configure the `spring.graphql.websocket.path` property in your application
143-
and have the required dependencies on classpath. In the case of a Servlet application, adding the `spring-boot-starter-websocket` should be enough.
144-
145-
WebSocket support comes with dedicated properties:
146-
147-
````properties
148-
# Path of the GraphQL WebSocket subscription endpoint.
149-
spring.graphql.websocket.path=/graphql/websocket
150-
# Time within which the initial {@code CONNECTION_INIT} type message must be received.
151-
spring.graphql.websocket.connection-init-timeout=60s
152-
````
153-
154-
### Extension points
155-
156-
You can contribute [`WebInterceptor` beans](https://github.com/spring-projects-experimental/spring-graphql/blob/master/spring-graphql/src/main/java/org/springframework/graphql/WebInterceptor.java)
157-
to the application context, so as to customize the `ExecutionInput` or the `ExecutionResult` of the query.
158-
A custom `WebInterceptor` can, for example, change the HTTP request/response headers.
159-
160-
### Testing support
161-
162-
When the `spring-boot-starter-test` dependency is on the classpath, Spring GraphQL provides a testing infrastructure for your application.
163-
164-
Spring Boot allows you to test your web application with [with a mock environment](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.testing.spring-boot-applications.with-mock-environment)
165-
or [with a running server](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.testing.spring-boot-applications.with-running-server).
166-
In both cases, adding the `@AutoConfigureGraphQlTester` annotation on your test class will contribute a `GraphQlTester` bean you can inject and use in your tests:
167-
168-
```` java
169-
@SpringBootTest
170-
@AutoConfigureMockMvc
171-
@AutoConfigureGraphQlTester
172-
public class MockMvcGraphQlTests {
173-
174-
@Autowired
175-
private GraphQlTester graphQlTester;
176-
177-
@Test
178-
void jsonPath() {
179-
String query = "{" +
180-
" project(slug:\"spring-framework\") {" +
181-
" releases {" +
182-
" version" +
183-
" }" +
184-
" }" +
185-
"}";
186-
187-
this.graphQlTester.query(query)
188-
.execute()
189-
.path("project.releases[*].version")
190-
.entityList(String.class)
191-
.hasSizeGreaterThan(1);
192-
}
193-
}
194-
````
195-
196-
### Metrics
197-
198-
If the `spring-boot-starter-actuator` dependency is on the classpath, metrics will be collected for GraphQL requests.
199-
You can see those metrics by exposing the metrics endpoint with `application.properties`:
200-
```properties
201-
management.endpoints.web.exposure.include=health,metrics,info
202-
```
203-
204-
#### GraphQL Request (timer)
205-
206-
A Request metric timer is available at `/actuator/metrics/graphql.request`.
207-
208-
| Tag | Description | Sample values |
209-
|---------|-----------------|--------------------|
210-
| outcome | Request outcome | "SUCCESS", "ERROR" |
211-
212-
213-
#### GraphQL Data Fetcher (timer)
3+
[GraphQL](https://graphql.org/) support for Spring applications with [GraphQL Java](https://github.com/graphql-java/graphql-java).
2144

215-
A Data Fetcher metric timer is available at `/actuator/metrics/graphql.datafetcher`.
5+
## Code of Conduct
2166

217-
| Tag | Description | Sample values |
218-
|---------|-----------------------|--------------------|
219-
| path | data fetcher path | "Query.project" |
220-
| outcome | data fetching outcome | "SUCCESS", "ERROR" |
7+
This project is governed by the [Spring Code of Conduct](CODE_OF_CONDUCT.adoc). By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to [email protected].
2218

9+
## Documentation
22210

223-
#### GraphQL Error (counter)
11+
This project maintains its reference documentation ([published](https://docs.spring.io/spring-grapqhl/docs/current-SNAPSHOT/spring-graphql-reference/) and [source](docs/src/docs/asciidoc)) and an
12+
[API reference](https://docs.spring.io/spring-graphql/docs/current-SNAPSHOT/javadoc-api/).
22413

225-
A counter metric counter is available at `/actuator/metrics/graphql.error`.
22614

227-
| Tag | Description | Sample values |
228-
|-----------|-----------------|-------------------------|
229-
| errorType | error type | "DataFetchingException" |
230-
| errorPath | error JSON Path | "$.project" |
15+
## Continuous Integration Builds
23116

232-
## Sample applications
17+
Information regarding CI builds can be found in the [Spring GraphQL Concourse pipeline](ci/README.adoc) documentation.
23318

234-
This repository contains sample applications that the team is using to test new features and ideas.
19+
## Stay in Touch
23520

236-
You can run them by cloning this repository and typing on the command line:
21+
Follow [@SpringCentral](https://twitter.com/springcentral).
23722

238-
```shell script
239-
$ ./gradlew :samples:webmvc-http:bootRun
240-
$ ./gradlew :samples:webflux-websocket:bootRun
241-
```
24223

24324

24425
## License

0 commit comments

Comments
 (0)