yume/juniper
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix up Cargo.toml files and documentation.

Browse source
This commit is contained in:
theduke 2017-12-02 16:09:08 +01:00
parent b89712a887
commit 4d6a99fe4e
9 changed files with 211 additions and 248 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
Cargo.toml
View file

@ -4,4 +4,5 @@ members = [
"juniper_codegen",
"juniper_tests",
"juniper_iron",
"juniper_rocket",
]

178
README.md
View file

@ -13,159 +13,87 @@
---
[GraphQL][graphql] is a data query language developed by Facebook intended to
serve mobile and web application frontends. Juniper makes it possible to write
GraphQL servers in Rust that are type-safe and blazingly fast.
serve mobile and web application frontends.
*Juniper* makes it possible to write GraphQL servers in Rust that are
type-safe and blazingly fast. We also try to make declaring and resolving
GraphQL schemas as convenient as possible as Rust will allow.
Juniper does not include a web server - instead it provides building blocks to
make integration with existing servers straightforward. It optionally provides a
pre-built integration for the [Iron][iron] and [Rocket] frameworks.
pre-built integration for the [Iron][iron] and [Rocket] frameworks, including
embedded [Graphiql][graphiql] for easy debugging.
* [Cargo crate](https://crates.io/crates/juniper)
* [API Documentation](https://docs.rs/juniper)
* [API Reference][docsrs]
* [Book][book]: Guides and Examples
## Installation
Add Juniper to your Cargo.toml:
## Getting Started
```toml
[dependencies]
juniper = { git = "https://github.com/graphql-rust/juniper" }
```
The best place to get started is the [Juniper Book][book], which contains
guides with plenty of examples, covering all features of Juniper.
If you want Iron integration, you need to depend on the `juniper_iron` crate.
feature flag:
To get started quickly and get a feel for Juniper, check out the
[Quickstart][book_quickstart] section.
```toml
[dependencies]
juniper = { git = "https://github.com/graphql-rust/juniper" }
juniper_iron = { git = "https://github.com/graphql-rust/juniper_iron" }
For specific information about macros, types and the Juniper api, the
[API Reference][docsrs] is the best place to look.
```
You can also check out [src/tests/schema.rs][test_schema_rs] to see a complex
schema including polymorphism with traits and interfaces.
For an example of web framework integration,
see the [rocket][rocket_examples] and [iron][iron_examples] examples folders.
If you want Rocket integration, you need to depend on the `juniper_rocket` crate.
**Note**: Until 0.9 is released, you will need to use a Git dependency to the current master branch.
```toml
[dependencies]
juniper = { git = "https://github.com/graphql-rust/juniper" }
juniper_rocket = { git = "https://github.com/graphql-rust/juniper_rocket" }
```
## Building schemas
GraphQL turns the REST paradigm as it's usually implemented on its head: instead
of providing a fixed structure of all types and relations in the system, GraphQL
defines a _schema_ which your users can query. The schema defines all types,
fields, and relations available, while the query defines which fields and
relations a user is interested in.
Juniper expects you to already have the types you want to expose in GraphQL as
Rust data types. Other than that, it doesn't make any assumptions whether they
are stored in a database or just in memory. Exposing a type is a matter of
implementing the `GraphQLType` for your type. To make things a bit easier,
Juniper comes with a set of macros that help you do this, based on what kind of
type you want to expose. Let's look at how one could expose parts of the [Star
Wars Schema][swschema]:
```rust
#[macro_use] extern crate juniper;
use juniper::FieldResult;
enum Episode {
NewHope,
Empire,
Jedi,
}
struct Human {
id: String,
name: String,
appears_in: Vec<Episode>,
home_planet: String,
}
graphql_enum!(Episode {
Episode::NewHope => "NEW_HOPE",
Episode::Empire => "EMPIRE",
Episode::Jedi => "JEDI",
});
graphql_object!(Human: () |&self| {
description: "A humanoid creature in the Star Wars universe"
// Field resolver methods look almost like ordinary methods. The macro picks
// up arguments and return types for the introspection schema, and verifies
// it during compilation.
field id() -> FieldResult<&String> {
Ok(&self.id)
}
field name() -> FieldResult<&String> {
Ok(&self.name)
}
field appears_in() -> FieldResult<&Vec<Episode>> {
Ok(&self.appears_in)
}
field home_planet() -> FieldResult<&String> {
Ok(&self.home_planet)
}
});
```
You can find the full example in [src/tests/schema.rs][test_schema_rs],
including polymorphism with traits and interfaces. For an example of framework
integration, see the [rocket][rocket_examples] and [iron][iron_examples] examples folders.
## Features
Juniper supports the full GraphQL query language according to the
[specification][graphql_spec], including the introspective schema and all
validations. It does not, however, support the schema language.
[specification][graphql_spec], including interfaces, unions, schema
introspection, and validations.
It does not, however, support the schema language.
As an exception to other GraphQL libraries for other languages, Juniper builds
non-null types by default. A field of type `Vec<Episode>` will be converted into
`[Episode!]!`. The corresponding Rust type for e.g. `[Episode]` would be
`Option<Vec<Option<Episode>>>`.
## Integrations
### Data types
Juniper has automatic integration with some very common Rust crates to make
building schemas a breeze. The types from these crates will be usable in
your Schemas automatically.
* [uuid][uuid]
* [url][url]
* [chrono][chrono]
### Web Frameworks
* [rocket][rocket]
* [iron][iron]
## API Stability
Juniper has not reached 1.0 yet, thus some API instability should be expected.
## 1.0 Roadmap
> Version 0.8.1 probably be re-released as 1.0 to indicate API stability.
The road to 1.0 _focuses_ on two aspects: making sure the API hasn't got any
obvious dead-ends with respect to probable future features, and improving test
coverage for general execution. There are some chores that need to be completed
as well.
* [X] Extensive execution testing
* [X] Sending input objects and partial input objects in variables
* [X] Sending enums in variables
* [X] General input value type checking and validation
* [X] Improve helper macros
* [X] `graphql_union!` helper completely missing
* [X] `graphql_input_object!` helper completely missing
* [X] Add support for deprecating things
* [X] Custom enum values and descriptions
* [X] Improved syntax for fields that can't fail resolution - make
`FieldResult<T>` optional maybe?
* [X] Investigate asynchronous execution - implementing it is not necessary, but
at least look at what API changes will be needed for us to hook into
[Tokio][tokio], for example.
* [X] Larger examples to illustrate things like database access
[graphql]: http://graphql.org
[graphiql]: https://github.com/graphql/graphiql
[iron]: http://ironframework.io
[swschema]: http://graphql.org/docs/typesystem/
[graphql_spec]: http://facebook.github.io/graphql
[test_schema_rs]: juniper/src/tests/schema.rs
[test_schema_rs]: https://github.com/graphql-rust/juniper/blob/master/src/tests/schema.rs
[tokio]: https://github.com/tokio-rs/tokio
[rocket_examples]: https://github.com/graphql-rust/juniper_rocket/tree/master/examples
[iron_examples]: https://github.com/graphql-rust/juniper_iron/tree/master/examples
[rocket_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_rocket/examples
[iron_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_iron/examples
[Rocket]: https://rocket.rs
[book]: https://graphql-rust.github.io/juniper-book
[book_quickstart]: https://graphql-rust.github.io/juniper-book/quickstart.html
[docsrs]: https://docs.rs/juniper
[uuid]: https://crates.io/crates/uuid
[url]: https://crates.io/crates/url
[chrono]: https://crates.io/crates/chrono

145
juniper/src/lib.rs
View file

@ -2,115 +2,90 @@
# GraphQL
[GraphQL][1] is a data query language developed by Facebook intended to serve
mobile and web application frontends. A server provides a schema, containing
types and fields that applications can query. Queries are hierarchical,
composable, and statically typed. Schemas are introspective, which lets clients
statically verify their queries against a server without actually executing
them.
[GraphQL][graphql] is a data query language developed by Facebook intended to
serve mobile and web application frontends.
This library provides data types and traits to expose Rust types in a GraphQL
schema, as well as an optional integration into the [Iron framework][Iron] and
[Rocket]. It tries to keep the number of dynamic operations to a minimum, and
give you as the schema developer the control of the query execution path.
*Juniper* makes it possible to write GraphQL servers in Rust that are
type-safe and blazingly fast. We also try to make declaring and resolving
GraphQL schemas as convenient as possible as Rust will allow.
## Exposing data types
Juniper does not include a web server - instead it provides building blocks to
make integration with existing servers straightforward. It optionally provides a
pre-built integration for the [Iron][iron] and [Rocket] frameworks, including
embedded [Graphiql][graphiql] for easy debugging.
The `GraphQLType` trait is the primary interface towards application developers.
By implementing this trait, you can expose your types as either objects, enums,
interfaces, unions, or scalars.
* [Cargo crate](https://crates.io/crates/juniper)
* [API Reference][docsrs]
* [Book][book]: Guides and Examples
However, due to the dynamic nature of GraphQL's type system, doing this
manually is a bit tedious, especially in order to do it in a fully type safe
manner.
The library provides two methods of mapping your Rust data types to GraphQL schemas: custom derive
implementations and macros.
## Getting Started
```rust
# use std::collections::HashMap;
# #[macro_use] extern crate juniper;
use juniper::{Context, FieldResult};
The best place to get started is the [Juniper Book][book], which contains
guides with plenty of examples, covering all features of Juniper.
struct User { id: String, name: String, friend_ids: Vec<String> }
struct QueryRoot;
struct Database { users: HashMap<String, User> }
To get started quickly and get a feel for Juniper, check out the
[Quickstart][book_quickstart] section.
impl Context for Database {}
For specific information about macros, types and the Juniper api, the
[API Reference][docsrs] is the best place to look.
// GraphQL objects can access a "context object" during execution. Use this
// object to provide e.g. database access to the field accessors. This object
// must implement the `Context` trait. If you don't need a context, use the
// empty tuple `()` to indicate this.
//
// In this example, we use the Database struct as our context.
graphql_object!(User: Database |&self| {
You can also check out [src/tests/schema.rs][test_schema_rs] to see a complex
schema including polymorphism with traits and interfaces.
For an example of web framework integration,
see the [rocket][rocket_examples] and [iron][iron_examples] examples folders.
// Expose a simple field as a GraphQL string.
field id() -> &String {
&self.id
}
field name() -> &String {
&self.name
}
## Features
// FieldResult<T> is an alias for Result<T, FieldError>, which can be
// converted to from anything that implements std::fmt::Display - simply
// return an error with a string using the ? operator from this method and
// it will be correctly inserted into the execution response.
field secret() -> FieldResult<&String> {
Err("Can't touch this".to_owned())?
}
Juniper supports the full GraphQL query language according to the
[specification][graphql_spec], including interfaces, unions, schema
introspection, and validations.
It does not, however, support the schema language.
// Field accessors can optionally take an "executor" as their first
// argument. This object can help guide query execution and provides
// access to the context instance.
//
// In this example, the context is used to convert the friend_ids array
// into actual User objects.
field friends(&executor) -> Vec<&User> {
self.friend_ids.iter()
.filter_map(|id| executor.context().users.get(id))
.collect()
}
});
As an exception to other GraphQL libraries for other languages, Juniper builds
non-null types by default. A field of type `Vec<Episode>` will be converted into
`[Episode!]!`. The corresponding Rust type for e.g. `[Episode]` would be
`Option<Vec<Option<Episode>>>`.
// The context object is passed down to all referenced types - all your exposed
// types need to have the same context type.
graphql_object!(QueryRoot: Database |&self| {
## Integrations
// Arguments work just like they do on functions.
field user(&executor, id: String) -> Option<&User> {
executor.context().users.get(&id)
}
});
### Data types
# fn main() { }
```
Juniper has automatic integration with some very common Rust crates to make
building schemas a breeze. The types from these crates will be usable in
your Schemas automatically.
Adding per type, field, and argument documentation is possible directly from
this macro. For more in-depth information on how to expose fields and types, see
the [`graphql_object!`][3] macro.
* [uuid][uuid]
* [url][url]
* [chrono][chrono]
### Built-in object type integrations
### Web Frameworks
Juniper has [built-in integrations][object_integrations] for converting existing object types to
GraphQL objects for popular crates.
* [rocket][rocket]
* [iron][iron]
## Integrating with web servers
The most obvious usecase is to expose the GraphQL schema over an HTTP endpoint.
To support this, Juniper offers additional crates that integrate with popular web frameworks.
## API Stability
* [juniper_iron][juniper_iron]: Handlers for [Iron][Iron]
* [juniper_rocket][juniper_rocket]: Handlers for [Rocket][Rocket]
Juniper has not reached 1.0 yet, thus some API instability should be expected.
[1]: http://graphql.org
[3]: macro.graphql_object!.html
[Iron]: http://ironframework.io
[graphql]: http://graphql.org
[graphiql]: https://github.com/graphql/graphiql
[iron]: http://ironframework.io
[graphql_spec]: http://facebook.github.io/graphql
[test_schema_rs]: https://github.com/graphql-rust/juniper/blob/master/juniper/src/tests/schema.rs
[tokio]: https://github.com/tokio-rs/tokio
[rocket_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_rocket/examples
[iron_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_iron/examples
[Rocket]: https://rocket.rs
[object_integrations]: integrations/index.html
[book]: https://graphql-rust.github.io/juniper-book
[book_quickstart]: https://graphql-rust.github.io/juniper-book/quickstart.html
[docsrs]: https://docs.rs/juniper
[uuid]: https://crates.io/crates/uuid
[url]: https://crates.io/crates/url
[chrono]: https://crates.io/crates/chrono
*/
#![warn(missing_docs)]

11
juniper_iron/Cargo.toml
View file

@ -8,18 +8,23 @@ documentation = "https://docs.rs/juniper_iron"
repository = "https://github.com/graphql-rust/juniper_iron"
[dependencies]
serde = { version = "1.0.2" }
serde = { version = "1.0.8" }
serde_json = { version = "1.0.2" }
juniper = { version = "0.9.0", path = "../juniper" }
urlencoded = { version = "0.5.0" }
iron = "0.5.1"
juniper = { version = "0.8.1", git = "https://github.com/graphql-rust/juniper" }
[dev-dependencies]
iron-test = "^0.5.0"
router = "^0.5.0"
mount = "^0.3.0"
logger = "^0.3.0"
juniper = { version = "0.8.1", features = ["expose-test-schema", "serde_json"], git = "https://github.com/graphql-rust/juniper" }
[dev-dependencies.juniper]
version = "0.9.0"
features = ["expose-test-schema", "serde_json"]
path = "../juniper"
[badges]
travis-ci = { repository = "graphql-rust/juniper_iron" }

24
juniper_iron/README.md
View file

@ -1,23 +1,22 @@
# juniper_iron
[![Build Status](https://travis-ci.org/graphql-rust/juniper_iron.svg?branch=master)](https://travis-ci.org/graphql-rust/juniper_iron)
[![Build status](https://ci.appveyor.com/api/projects/status/rqguvfkl9m0g7hum?svg=true)](https://ci.appveyor.com/project/theduke/juniper-iron)
[![Crates.io](https://img.shields.io/crates/v/juniper_iron.svg?maxAge=2592000)](https://crates.io/crates/juniper_iron)
[![Gitter chat](https://badges.gitter.im/juniper-graphql/gitter.png)](https://gitter.im/juniper-graphql)
This repository contains the [Iron][Iron] web framework integration for
[Juniper][Juniper], a [GraphQL][GraphQL] implementation for Rust.
This repository contains the [Iron][Iron] web framework integration for [Juniper][Juniper], a [GraphQL][GraphQL]
implementation for Rust.
For documentation, including guides and examples, check out [Juniper][Juniper].
## Documentation
Once the crate is published, documentation will be on [docs.rs][documentation].
For now, please consult the documentation comments [here](https://github.com/graphql-rust/juniper_iron/blob/master/src/lib.rs).
A basic usage example can also be found in the [Api documentation][documentation].
## Examples
Check [examples/iron_server.rs][example] for example code of a working Iron server with GraphQL handlers.
## Links
* [Juniper][Juniper]
* [Api Reference][documetation]
* [Iron framework][Iron]
## License
This project is under the BSD-2 license.
@ -28,4 +27,5 @@ Check the LICENSE file for details.
[Juniper]: https://github.com/graphql-rust/juniper
[GraphQL]: http://graphql.org
[documentation]: https://docs.rs/juniper_iron
[example]: https://github.com/graphql-rust/juniper_iron/blob/master/examples/iron_server.rs
[example]: https://github.com/graphql-rust/juniper/blob/master/juniper_iron/examples/iron_server.rs

28
juniper_iron/src/lib.rs
View file

@ -1,11 +1,23 @@
/*!
[Juniper][1] handlers for the [Iron][2] framework.
# juniper_iron
This repository contains the [Iron][Iron] web framework integration for
[Juniper][Juniper], a [GraphQL][GraphQL] implementation for Rust.
For documentation, including guides and examples, check out [Juniper][Juniper].
A basic usage example can also be found in the [Api documentation][documentation].
## Links
* [Juniper][Juniper]
* [Api Reference][documentation]
* [Iron framework][Iron]
## Integrating with Iron
For example, continuing from the schema created above and using Iron to expose
the schema on an HTTP endpoint supporting both GET and POST requests:
@ -78,18 +90,14 @@ fn main() {
```
See the [iron_server.rs][5]
example for more information on how to use these handlers.
See the the [`GraphQLHandler`][3] documentation for more information on what request methods are
supported.
There's also a built-in [GraphiQL][4] handler included.
[1]: https://github.com/mhallin/Juniper
[2]: http://ironframework.io
[3]: ./struct.GraphQLHandler.html
[4]: https://github.com/graphql/graphiql
[5]: https://github.com/mhallin/juniper/blob/master/juniper_iron/examples/iron_server.rs
[Iron]: https://github.com/iron/iron
[Juniper]: https://github.com/graphql-rust/juniper
[GraphQL]: http://graphql.org
[documentation]: https://docs.rs/juniper_iron
*/

10
juniper_rocket/Cargo.toml
View file

@ -11,13 +11,17 @@ repository = "https://github.com/graphql-rust/juniper_rocket"
serde = { version = "1.0.8" }
serde_derive = {version="1.0.8" }
serde_json = { version = "1.0.2" }
juniper = { version = "0.9.0" , path = "../juniper"}
rocket = { version = "0.3.0" }
rocket_codegen = { version = "0.3.0" }
juniper = { version = "0.8.1" , git = "https://github.com/graphql-rust/juniper" }
[badges]
travis-ci = { repository = "mhallin/juniper" }
appveyor = { repository = "mhallin/juniper" }
[dev-dependencies]
juniper = { version = "0.8.1", path = "../juniper", features=["expose-test-schema", "serde_json"], git = "https://github.com/graphql-rust/juniper" }
[dev-dependencies.juniper]
version = "0.9.0"
features = ["expose-test-schema", "serde_json"]
path = "../juniper"

24
juniper_rocket/README.md
View file

@ -1,22 +1,24 @@
# juniper_rocket
[![Build Status](https://travis-ci.org/graphql-rust/juniper_rocket.svg?branch=master)](https://travis-ci.org/graphql-rust/juniper_rocket)
[![Build status](https://ci.appveyor.com/api/projects/status/9j9bvj7q05jcxw2v?svg=true)](https://ci.appveyor.com/project/theduke/juniper-rocket)
[![Crates.io](https://img.shields.io/crates/v/juniper_rocket.svg?maxAge=2592000)](https://crates.io/crates/juniper_rocket)
[![Gitter chat](https://badges.gitter.im/juniper-graphql/gitter.png)](https://gitter.im/juniper-graphql)
This repository contains the [Rocket][Rocket] web server integration for [Juniper][Juniper], a [GraphQL][GraphQL]
implementation for Rust.
This repository contains the [Rocket][Rocket] web server integration for
[Juniper][Juniper], a [GraphQL][GraphQL] implementation for Rust.
## Documentation
Once the crate is published, the documentation will be on [docs.rs][documentation].
For documentation, including guides and examples, check out [Juniper][Juniper].
For now, please consult the example below.
A basic usage example can also be found in the [Api documentation][documentation].
## Examples
Check [examples/rocket_server.rs][example] for example code of a working Rocket server with GraphQL handlers.
Check [examples/rocket_server.rs][example] for example code of a working Rocket
server with GraphQL handlers.
## Links
* [Juniper][Juniper]
* [Api Reference][documetation]
* [Rocket][Iron]
## License
@ -29,3 +31,5 @@ Check the LICENSE file for details.
[GraphQL]: http://graphql.org
[documentation]: https://docs.rs/juniper_rocket
[example]: https://github.com/graphql-rust/juniper_rocket/blob/master/examples/rocket_server.rs

38
juniper_rocket/src/lib.rs
View file

@ -1,3 +1,41 @@
/*!
# juniper_rocket
This repository contains the [Rocket][Rocket] web server integration for
[Juniper][Juniper], a [GraphQL][GraphQL] implementation for Rust.
## Documentation
For documentation, including guides and examples, check out [Juniper][Juniper].
A basic usage example can also be found in the [Api documentation][documentation].
## Examples
Check [examples/rocket_server.rs][example] for example code of a working Rocket
server with GraphQL handlers.
## Links
* [Juniper][Juniper]
* [Api Reference][documentation]
* [Rocket][Rocket]
## License
This project is under the BSD-2 license.
Check the LICENSE file for details.
[Rocket]: https://rocket.rs
[Juniper]: https://github.com/graphql-rust/juniper
[GraphQL]: http://graphql.org
[documentation]: https://docs.rs/juniper_rocket
[example]: https://github.com/graphql-rust/juniper_rocket/blob/master/examples/rocket_server.rs
*/
#![feature(plugin)]
#![plugin(rocket_codegen)]