Skip to content

Commit 781b447

Browse files
rasmusjprasmusjp
committed
Add CONTRIBUTING, CHANGELOG and minimal documentation
1 parent 762a8c1 commit 781b447

File tree

4 files changed

+145
-39
lines changed

4 files changed

+145
-39
lines changed

‎CHANGELOG.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Change log
2+
3+
All notable changes to this project will be documented in this file.
4+
This project adheres to [Semantic Versioning](http://semver.org/).
5+
6+
## 0.1.0 - 2018-10-12
7+
8+
- First release

‎CONTRIBUTING.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Contributing
2+
3+
## Bug Reports & Feature Requests
4+
5+
Please use the [issue tracker](https://github.com/rasmusjp/umbraco-graphql/issues) to report any bugs or file feature requests.
6+
7+
## Developing
8+
9+
### Prerequisites
10+
11+
- Visual Studio
12+
- IIS Express
13+
14+
### Setup
15+
16+
First build the Solution
17+
18+
Run the `samples/Website` project, this will start IIS Express listeninng on `http://localhost:49937`
19+
20+
Install Umbraco with the starter kit, so you have some sample data.
21+
22+
### Folder structure
23+
24+
```
25+
.
26+
├── samples # Sample projects
27+
│   └── Website # Sample/development site
28+
├── src # Source Files
29+
│   └── Our.Umbraco.GraphQL # Main Project
30+
├── test # Tests Projects
31+
│   └── Our.Umbraco.GraphQL.Tests # Unit Tests
32+
└── tools # Build tools
33+
```

‎README.md

Lines changed: 37 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,15 @@ Please note this **should not be used in production**, since there are **no secu
1010

1111
## How does it work
1212

13-
An Owin middleware exposes Umbraco Published Content as a GraphQL endpoint.
14-
15-
GraphQL types are dynamically generated for all Umbraco document types (content and media), with all the properties as fields. They all implement an interface `PublishedContent` which implements the generic Umbraco properties as fields.
13+
GraphQL types are dynamically generated for all Umbraco document types (content and media), with all the properties as fields.
1614

1715
## Installation
1816

1917
The preferred way to install GraphQL for Umbraco is through NuGet
2018

2119
### Option 1: NuGet
2220

23-
GraphQL for Umbraco is available as a NuGet [package](https://www.nuget.org/packages/Our.Umbraco.GraphQL).
21+
GraphQL for Umbraco is available as a [NuGet package](https://www.nuget.org/packages/Our.Umbraco.GraphQL).
2422

2523
To install run the following command in the [Package Manager Console](https://docs.nuget.org/docs/start-here/using-the-package-manager-console)
2624

@@ -32,40 +30,40 @@ PM> Install-Package Our.Umbraco.GraphQL
3230

3331
Clone the repository and run the Website (F5 in Visual Studio), install Umbraco with the starter kit and start exploring the API using the GraphQL Playground by opening `/umbraco/graphql`.
3432

35-
### Urls
36-
37-
| Method | Url | Description |
38-
| ------ | ---------------- | ------------------ |
39-
| GET | /umbraco/graphql | GraphQL Playground |
40-
| POST | /umbraco/graphql | GraphQL endpoint |
41-
42-
### Querying
43-
44-
The Umbraco queries/types can be found under the `umbraco` field.
45-
46-
```graphql
47-
{
48-
umbraco {
49-
content {
50-
atRoot {
51-
all {
52-
...
53-
}
54-
...
55-
}
56-
byId(id: "id") {
57-
}
58-
byType {
59-
...
60-
}
61-
byUrl(url: "url") {
62-
...
63-
}
64-
}
65-
}
66-
}
67-
```
33+
## Docs
34+
35+
The docs can be found [here](docs/index.md)
36+
37+
## TODO
38+
39+
- [x] GraphQL Playground
40+
- [x] Schema Stitching (extending types)
41+
- [x] Metrics
42+
- [x] Published Content
43+
- [ ] Published Media
44+
- [ ] Dictionary
45+
- [ ] Statistics (field usage etc.)
46+
- [ ] Deprecation (Content Types and Properties)
47+
- [ ] API Tokens (OAUTH) with permissions (for content types and properties)
48+
- [ ] Data Types
49+
- [ ] Document Types
50+
- [ ] Media Types
51+
- [ ] Member Types
52+
- [ ] Content
53+
- [ ] Media
54+
- [ ] Members
55+
- [ ] Documentation
56+
57+
## Contributing
58+
59+
Anyone can help make this project better - check out our [Contributing guide](CONTRIBUTING.md)
60+
61+
## Authors
62+
63+
- [Rasmus John Pedersen](https://www.github.com/rasmusjp)
64+
65+
## License
6866

69-
### Extending the Schema with your own types
67+
Copyright © 2018 Rasmus John Pedersen
7068

71-
Take a look at the [Star Wars sample](samples/Website/Starwars).
69+
GraphQL for Umbraco is released under the [MIT License](LICENSE)

‎docs/index.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Documentation
2+
3+
## Configuration
4+
5+
When installing the [NuGet package](https://www.nuget.org/packages/Our.Umbraco.GraphQL) a new file `App_Start/GraphQLComponent.cs` is added to the project, it contains the bootstrapping code for adding GraphQL to the project and the default configuration
6+
7+
```csharp
8+
var path = $"/{_globalSettings.GetUmbracoMvcArea()}/graphql";
9+
10+
app.UseUmbracoGraphQL(path, _factory, opts =>
11+
{
12+
opts.Debug = HostingEnvironment.IsDevelopmentEnvironment;
13+
opts.EnableMetrics = true;
14+
opts.EnableMiniProfiler = false;
15+
opts.EnablePlayground = true;
16+
});
17+
```
18+
19+
The configuration options are:
20+
21+
| Option | Description |
22+
| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
23+
| CorsPolicyProvider | The Cors Policy Provider |
24+
| Debug | Should exceptions be exposed in the response |
25+
| EnableMetrics | Should metrics be enabled |
26+
| EnableMiniProfiler | Should MiniProfiler be enabled |
27+
| EnablePlayground | Should the GraphQL Playground be enabled |
28+
| PlaygroundSettings | Custom settings for the [GraphQL Playground](https://github.com/prisma-labs/graphql-playground#settings) |
29+
| SetCorsPolicy(CorsPolicy policy) | Sets the Cors Policy |
30+
31+
## Default Urls
32+
33+
| Method | Url | Description |
34+
| ------ | ---------------- | ------------------ |
35+
| GET | /umbraco/graphql | GraphQL Playground |
36+
| POST | /umbraco/graphql | GraphQL endpoint |
37+
38+
## Querying
39+
40+
The Umbraco queries/types can be found under the `umbraco` field.
41+
42+
```graphql
43+
{
44+
umbraco {
45+
content {
46+
atRoot {
47+
all {
48+
}
49+
# ... document types are added as fields
50+
}
51+
byId(id: "id") {
52+
}
53+
byType {
54+
# ... document types are added as fields
55+
}
56+
byUrl(url: "url") {
57+
}
58+
}
59+
}
60+
}
61+
```
62+
63+
## Metrics
64+
65+
[Apollo Tracing](https://github.com/apollographql/apollo-tracing) is enabled by default and is displayed in the GraphQL Playground, it collects the execution time for each field.
66+
67+
If you need more insight, [Miniprofiler](https://miniprofiler.com/dotnet/) can be enabled by setting the option `EnableMiniprofiler=true`, MiniProfiler is implemented throughout the Umbraco code base and collects a lot of metrics. The data will be accessiblo in the `extensions.miniProfiler` field in the response.

0 commit comments

Comments
 (0)