diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2cf21b7 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,8 @@ +# Change log + +All notable changes to this project will be documented in this file. +This project adheres to [Semantic Versioning](http://semver.org/). + +## 0.1.0 - 2018-10-12 + +- First release diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..81967e0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# Contributing + +## Bug Reports & Feature Requests + +Please use the [issue tracker](https://github.com/rasmusjp/umbraco-graphql/issues) to report any bugs or file feature requests. + +## Developing + +### Prerequisites + +- Visual Studio +- IIS Express + +### Setup + +First build the Solution + +Run the `samples/Website` project, this will start IIS Express listeninng on `http://localhost:49937` + +Install Umbraco with the starter kit, so you have some sample data. + +### Folder structure + +``` +. +├── samples # Sample projects +│   └── Website # Sample/development site +├── src # Source Files +│   └── Our.Umbraco.GraphQL # Main Project +├── test # Tests Projects +│   └── Our.Umbraco.GraphQL.Tests # Unit Tests +└── tools # Build tools +``` diff --git a/README.md b/README.md index ccd8703..e6ee465 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,7 @@ Please note this **should not be used in production**, since there are **no secu ## How does it work -An Owin middleware exposes Umbraco Published Content as a GraphQL endpoint. - -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. +GraphQL types are dynamically generated for all Umbraco document types (content and media), with all the properties as fields. ## Installation @@ -20,7 +18,7 @@ The preferred way to install GraphQL for Umbraco is through NuGet ### Option 1: NuGet -GraphQL for Umbraco is available as a NuGet [package](https://www.nuget.org/packages/Our.Umbraco.GraphQL). +GraphQL for Umbraco is available as a [NuGet package](https://www.nuget.org/packages/Our.Umbraco.GraphQL). To install run the following command in the [Package Manager Console](https://docs.nuget.org/docs/start-here/using-the-package-manager-console) @@ -32,40 +30,40 @@ PM> Install-Package Our.Umbraco.GraphQL 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`. -### Urls - -| Method | Url | Description | -| ------ | ---------------- | ------------------ | -| GET | /umbraco/graphql | GraphQL Playground | -| POST | /umbraco/graphql | GraphQL endpoint | - -### Querying - -The Umbraco queries/types can be found under the `umbraco` field. - -```graphql -{ - umbraco { - content { - atRoot { - all { - ... - } - ... - } - byId(id: "id") { - } - byType { - ... - } - byUrl(url: "url") { - ... - } - } - } -} -``` +## Docs + +The docs can be found [here](docs/index.md) + +## TODO + +- [x] GraphQL Playground +- [x] Schema Stitching (extending types) +- [x] Metrics +- [x] Published Content +- [ ] Published Media +- [ ] Dictionary +- [ ] Statistics (field usage etc.) +- [ ] Deprecation (Content Types and Properties) +- [ ] API Tokens (OAUTH) with permissions (for content types and properties) +- [ ] Data Types +- [ ] Document Types +- [ ] Media Types +- [ ] Member Types +- [ ] Content +- [ ] Media +- [ ] Members +- [ ] Documentation + +## Contributing + +Anyone can help make this project better - check out our [Contributing guide](CONTRIBUTING.md) + +## Authors + +- [Rasmus John Pedersen](https://www.github.com/rasmusjp) + +## License -### Extending the Schema with your own types +Copyright © 2018 Rasmus John Pedersen -Take a look at the [Star Wars sample](samples/Website/Starwars). +GraphQL for Umbraco is released under the [MIT License](LICENSE) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5e4a4b7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,67 @@ +# Documentation + +## Configuration + +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 + +```csharp +var path = $"/{_globalSettings.GetUmbracoMvcArea()}/graphql"; + +app.UseUmbracoGraphQL(path, _factory, opts => +{ + opts.Debug = HostingEnvironment.IsDevelopmentEnvironment; + opts.EnableMetrics = true; + opts.EnableMiniProfiler = false; + opts.EnablePlayground = true; +}); +``` + +The configuration options are: + +| Option | Description | +| -------------------------------- | -------------------------------------------------------------------------------------------------------- | +| CorsPolicyProvider | The Cors Policy Provider | +| Debug | Should exceptions be exposed in the response | +| EnableMetrics | Should metrics be enabled | +| EnableMiniProfiler | Should MiniProfiler be enabled | +| EnablePlayground | Should the GraphQL Playground be enabled | +| PlaygroundSettings | Custom settings for the [GraphQL Playground](https://github.com/prisma-labs/graphql-playground#settings) | +| SetCorsPolicy(CorsPolicy policy) | Sets the Cors Policy | + +## Default Urls + +| Method | Url | Description | +| ------ | ---------------- | ------------------ | +| GET | /umbraco/graphql | GraphQL Playground | +| POST | /umbraco/graphql | GraphQL endpoint | + +## Querying + +The Umbraco queries/types can be found under the `umbraco` field. + +```graphql +{ + umbraco { + content { + atRoot { + all { + } + # ... document types are added as fields + } + byId(id: "id") { + } + byType { + # ... document types are added as fields + } + byUrl(url: "url") { + } + } + } +} +``` + +## Metrics + +[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. + +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.