1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
#![deny(missing_debug_implementations, missing_copy_implementations, trivial_casts, trivial_numeric_casts, unsafe_code, unstable_features, unused_import_braces, unused_qualifications )] #![doc(html_root_url = "https://docs.rs/jsonapi/")] //! This is documentation for the `jsonapi` crate. //! The crate is meant to be used for serializing, deserializing and validating //! [JSON:API] requests and responses. //! //! [JSON:API]: https://jsonapi.org/ //! [serde]: https://serde.rs //! [JsonApiDocument]: api/struct.JsonApiDocument.html //! [Resource]: api/struct.Resource.html //! [jsonapi_model]: macro.jsonapi_model.html //! //! ## Examples //! //! ### Basic Usage with Macro //! //! Using the [`jsonapi_model!`][jsonapi_model] macro a struct can be converted //! into a [`JsonApiDocument`][JsonApiDocument] or [`Resource`][Resource]. It is //! required that the struct have an `id` property whose type is `String`. The //! second argument in the [`jsonapi_model!`][jsonapi_model] marco defines the //! `type` member as required by the [JSON:API] specification //! //! ```rust //! #[macro_use] extern crate serde_derive; //! #[macro_use] extern crate jsonapi; //! use jsonapi::api::*; //! use jsonapi::model::*; //! //! #[derive(Debug, PartialEq, Serialize, Deserialize)] //! struct Flea { //! id: String, //! name: String, //! }; //! //! jsonapi_model!(Flea; "flea"); //! //! let example_flea = Flea { //! id: "123".into(), //! name: "Mr.Flea".into(), //! }; //! //! // Convert into a `JsonApiDocument` //! let doc = example_flea.to_jsonapi_document(); //! assert!(doc.is_valid()); //! //! // Convert into a `Resource` //! let resource = example_flea.to_jsonapi_resource(); //! ``` //! //! ### Deserializing a JSON:API Document //! //! Deserialize a JSON:API document using [serde] by explicitly declaring the //! variable type in `Result` //! //! ```rust //! let serialized = r#" //! { //! "data": [{ //! "type": "articles", //! "id": "1", //! "attributes": { //! "title": "JSON:API paints my bikeshed!", //! "body": "The shortest article. Ever." //! }, //! "relationships": { //! "author": { //! "data": {"id": "42", "type": "people"} //! } //! } //! }], //! "included": [ //! { //! "type": "people", //! "id": "42", //! "attributes": { //! "name": "John" //! } //! } //! ] //! }"#; //! let data: Result<Resource, serde_json::Error> = serde_json::from_str(&serialized); //! assert_eq!(data.is_ok(), true); //! ``` //! //! Or parse the `String` directly using the //! [Resource::from_str](api/struct.Resource.html) trait implementation //! //! ```rust //! let data = Resource::from_str(&serialized); //! assert_eq!(data.is_ok(), true); //! ``` //! //! [`JsonApiDocument`][JsonApiDocument] implements `PartialEq` which allows two //! documents to be compared for equality. If two documents possess the **same //! contents** the ordering of the attributes and fields within the JSON:API //! document are irrelevant and their equality will be `true`. //! //! ## Testing //! //! Run the tests: //! //! ```text //! cargo test //! ``` //! //! Run tests with more verbose output: //! //! ```text //! RUST_BACKTRACE=1 cargo test -- --nocapture //! ``` //! //! Run tests whenever files are modified using `cargo watch`: //! //! ```text //! RUST_BACKTRACE=1 cargo watch "test -- --nocapture" //! ``` //! extern crate serde; extern crate serde_json; #[macro_use] extern crate serde_derive; extern crate queryst; #[macro_use] extern crate log; #[macro_use] extern crate error_chain; pub mod api; pub mod array; pub mod query; pub mod model; pub mod errors;