From a5fc657767f7a2c2c34abcfebabffdfa87d716c4 Mon Sep 17 00:00:00 2001 From: msrd0 Date: Thu, 20 May 2021 00:26:10 +0000 Subject: [PATCH] use cargo-doc2readme (#51) --- .github/workflows/rust.yml | 2 +- README.tpl => README.j2 | 9 +- README.md | 150 +++++++++++++++++----------------- crates-io.tpl => crates-io.j2 | 7 +- crates-io.md | 150 +++++++++++++++++----------------- readme.sh | 2 +- src/lib.rs | 2 +- src/response/raw.rs | 2 +- 8 files changed, 167 insertions(+), 157 deletions(-) rename README.tpl => README.j2 (91%) rename crates-io.tpl => crates-io.j2 (85%) diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 4a49fe8d80..2a62509edc 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -108,7 +108,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - uses: docker://ghcr.io/msrd0/alpine-cargo-readme + - uses: docker://ghcr.io/msrd0/cargo-doc2readme with: entrypoint: ./readme.sh args: --check diff --git a/README.tpl b/README.j2 similarity index 91% rename from README.tpl rename to README.j2 index d09d9853db..db9c5d7019 100644 --- a/README.tpl +++ b/README.j2 @@ -29,7 +29,7 @@ This repository contains the following crates: # gotham-restful -{{readme}} +{{ readme }} ## Versioning @@ -38,7 +38,7 @@ the MSRV (minimum supported rust version) is not considered a breaking change. ## License -Copyright (C) 2020-2021 Dominic Meiser and [contributors](https://github.com/msrd0/gotham_restful/graphs/contributors). +Copyright (C) 2020-2021 Dominic Meiser and [contributors]. ``` Licensed under the Apache License, Version 2.0 (the "License"); @@ -53,3 +53,8 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ``` + + [contributors]: https://github.com/msrd0/gotham_restful/graphs/contributors +{%- if links != "" %} +{{ links }} +{%- endif -%} diff --git a/README.md b/README.md index 42bb7b3d1c..861715bb9b 100644 --- a/README.md +++ b/README.md @@ -29,47 +29,47 @@ This repository contains the following crates: # gotham-restful -This crate is an extension to the popular [gotham web framework][gotham] for Rust. It allows you to -create resources with assigned endpoints that aim to be a more convenient way of creating handlers -for requests. +This crate is an extension to the popular [gotham web framework][__link0] for Rust. It allows you to create resources with assigned endpoints that aim to be a more convenient way of creating handlers for requests. + ## Features - Automatically parse **JSON** request and produce response bodies - Allow using **raw** request and response bodies - - Convenient **macros** to create responses that can be registered with gotham's router + - Convenient **macros** to create responses that can be registered with gotham’s router - Auto-Generate an **OpenAPI** specification for your API - - Manage **CORS** headers so you don't have to + - Manage **CORS** headers so you don’t have to - Manage **Authentication** with JWT - Integrate diesel connection pools for easy **database** integration + ## Safety -This crate is just as safe as you'd expect from anything written in safe Rust - and -`#![forbid(unsafe_code)]` ensures that no unsafe was used. +This crate is just as safe as you’d expect from anything written in safe Rust - and `#![forbid(unsafe_code)]` ensures that no unsafe was used. + ## Endpoints -There are a set of pre-defined endpoints that should cover the majority of REST APIs. However, -it is also possible to define your own endpoints. +There are a set of pre-defined endpoints that should cover the majority of REST APIs. However, it is also possible to define your own endpoints. + ### Pre-defined Endpoints Assuming you assign `/foobar` to your resource, the following pre-defined endpoints exist: -| Endpoint Name | Required Arguments | HTTP Verb | HTTP Path | -| ------------- | ------------------ | --------- | -------------- | -| read_all | | GET | /foobar | -| read | id | GET | /foobar/:id | -| search | query | GET | /foobar/search | -| create | body | POST | /foobar | -| update_all | body | PUT | /foobar | -| update | id, body | PUT | /foobar/:id | -| delete_all | | DELETE | /foobar | -| delete | id | DELETE | /foobar/:id | +| Endpoint Name | Required Arguments | HTTP Verb | HTTP Path | +| --- | --- | --- | --- | +| read_all | | GET | /foobar | +| read | id | GET | /foobar/:id | +| search | query | GET | /foobar/search | +| create | body | POST | /foobar | +| update_all | body | PUT | /foobar | +| update | id, body | PUT | /foobar/:id | +| delete_all | | DELETE | /foobar | +| delete | id | DELETE | /foobar/:id | + +Each of those endpoints has a macro that creates the neccessary boilerplate for the Resource. A simple example looks like this: -Each of those endpoints has a macro that creates the neccessary boilerplate for the Resource. A -simple example looks like this: ```rust /// Our RESTful resource. @@ -90,10 +90,11 @@ fn read(id: u64) -> Success { } ``` + ### Custom Endpoints -Defining custom endpoints is done with the `#[endpoint]` macro. The syntax is similar to that -of the pre-defined endpoints, but you need to give it more context: +Defining custom endpoints is done with the `#[endpoint]` macro. The syntax is similar to that of the pre-defined endpoints, but you need to give it more context: + ```rust use gotham_restful::gotham::hyper::Method; @@ -114,24 +115,22 @@ fn custom_endpoint(path: CustomPath) -> Success { } ``` + ## Arguments Some endpoints require arguments. Those should be - * **id** Should be a deserializable json-primitive like [`i64`] or [`String`]. - * **body** Should be any deserializable object, or any type implementing [`RequestBody`]. - * **query** Should be any deserializable object whose variables are json-primitives. It will - however not be parsed from json, but from HTTP GET parameters like in `search?id=1`. The - type needs to implement [`QueryStringExtractor`](gotham::extractor::QueryStringExtractor). -Additionally, all handlers may take a reference to gotham's [`State`]. Please note that for async -handlers, it needs to be a mutable reference until rustc's lifetime checks across await bounds -improve. + - **id** Should be a deserializable json-primitive like [`i64`][__link1] or [`String`][__link2]. + - **body** Should be any deserializable object, or any type implementing [`RequestBody`][__link3]. + - **query** Should be any deserializable object whose variables are json-primitives. It will however not be parsed from json, but from HTTP GET parameters like in `search?id=1`. The type needs to implement [`QueryStringExtractor`][__link4]. + +Additionally, all handlers may take a reference to gotham’s [`State`][__link5]. Please note that for async handlers, it needs to be a mutable reference until rustc’s lifetime checks across await bounds improve. + ## Uploads and Downloads -By default, every request body is parsed from json, and every respone is converted to json using -[serde_json]. However, you may also use raw bodies. This is an example where the request body -is simply returned as the response again, no json parsing involved: +By default, every request body is parsed from json, and every respone is converted to json using [serde_json][__link6]. However, you may also use raw bodies. This is an example where the request body is simply returned as the response again, no json parsing involved: + ```rust #[derive(Resource)] @@ -151,10 +150,11 @@ fn create(body : RawImage) -> Raw> { } ``` + ## Custom HTTP Headers -You can read request headers from the state as you would in any other gotham handler, and specify -custom response headers using [Response::header]. +You can read request headers from the state as you would in any other gotham handler, and specify custom response headers using [Response::header][__link7]. + ```rust #[derive(Resource)] @@ -172,10 +172,11 @@ async fn read_all(state: &mut State) -> NoContent { } ``` + ## Features -To make life easier for common use-cases, this create offers a few features that might be helpful -when you implement your web server. The complete feature list is +To make life easier for common use-cases, this create offers a few features that might be helpful when you implement your web server. The complete feature list is + - [`auth`](#authentication-feature) Advanced JWT middleware - `chrono` openapi support for chrono types - `full` enables all features except `without-openapi` @@ -186,16 +187,14 @@ when you implement your web server. The complete feature list is - `uuid` openapi support for uuid - `without-openapi` (**default**) disables `openapi` support. + ### Authentication Feature -In order to enable authentication support, enable the `auth` feature gate. This allows you to -register a middleware that can automatically check for the existence of an JWT authentication -token. Besides being supported by the endpoint macros, it supports to lookup the required JWT secret -with the JWT data, hence you can use several JWT secrets and decide on the fly which secret to use. -None of this is currently supported by gotham's own JWT middleware. +In order to enable authentication support, enable the `auth` feature gate. This allows you to register a middleware that can automatically check for the existence of an JWT authentication token. Besides being supported by the endpoint macros, it supports to lookup the required JWT secret with the JWT data, hence you can use several JWT secrets and decide on the fly which secret to use. None of this is currently supported by gotham’s own JWT middleware. A simple example that uses only a single secret looks like this: + ```rust #[derive(Resource)] #[resource(read)] @@ -232,14 +231,13 @@ fn main() { } ``` + ### CORS Feature -The cors feature allows an easy usage of this web server from other origins. By default, only -the `Access-Control-Allow-Methods` header is touched. To change the behaviour, add your desired -configuration as a middleware. +The cors feature allows an easy usage of this web server from other origins. By default, only the `Access-Control-Allow-Methods` header is touched. To change the behaviour, add your desired configuration as a middleware. + +A simple example that allows authentication from every origin (note that `*` always disallows authentication), and every content type, looks like this: -A simple example that allows authentication from every origin (note that `*` always disallows -authentication), and every content type, looks like this: ```rust #[derive(Resource)] @@ -265,18 +263,16 @@ fn main() { } ``` -The cors feature can also be used for non-resource handlers. Take a look at [`CorsRoute`] -for an example. +The cors feature can also be used for non-resource handlers. Take a look at [`CorsRoute`][__link8] for an example. + ### Database Feature -The database feature allows an easy integration of [diesel] into your handler functions. Please -note however that due to the way gotham's diesel middleware implementation, it is not possible -to run async code while holding a database connection. If you need to combine async and database, -you'll need to borrow the connection from the [`State`] yourself and return a boxed future. +The database feature allows an easy integration of [diesel][__link9] into your handler functions. Please note however that due to the way gotham’s diesel middleware implementation, it is not possible to run async code while holding a database connection. If you need to combine async and database, you’ll need to borrow the connection from the [`State`][__link10] yourself and return a boxed future. A simple non-async example looks like this: + ```rust #[derive(Resource)] #[resource(read_all)] @@ -306,16 +302,13 @@ fn main() { } ``` + ### OpenAPI Feature -The OpenAPI feature is probably the most powerful one of this crate. Definitely read this section -carefully both as a binary as well as a library author to avoid unwanted suprises. +The OpenAPI feature is probably the most powerful one of this crate. Definitely read this section carefully both as a binary as well as a library author to avoid unwanted suprises. + +In order to automatically create an openapi specification, gotham-restful needs knowledge over all routes and the types returned. `serde` does a great job at serialization but doesn’t give enough type information, so all types used in the router need to implement [`OpenapiType`][__link11]. This can be derived for almoust any type and there should be no need to implement it manually. A simple example looks like this: -In order to automatically create an openapi specification, gotham-restful needs knowledge over -all routes and the types returned. `serde` does a great job at serialization but doesn't give -enough type information, so all types used in the router need to implement -[`OpenapiType`](openapi_type::OpenapiType). This can be derived for almoust any type and there -should be no need to implement it manually. A simple example looks like this: ```rust #[derive(Resource)] @@ -348,18 +341,10 @@ fn main() { } ``` -Above example adds the resource as before, but adds two other endpoints as well: `/openapi` and `/`. -The first one will return the generated openapi specification in JSON format, allowing you to easily -generate clients in different languages without worying to exactly replicate your api in each of those -languages. The second one will return documentation in HTML format, so you can easily view your -api and share it with other people. +Above example adds the resource as before, but adds two other endpoints as well: `/openapi` and `/`. The first one will return the generated openapi specification in JSON format, allowing you to easily generate clients in different languages without worying to exactly replicate your api in each of those languages. The second one will return documentation in HTML format, so you can easily view your api and share it with other people. + +However, please note that by default, the `without-openapi` feature of this crate is enabled. Disabling it in favour of the `openapi` feature will add additional type bounds and method requirements to some of the traits and types in this crate, for example instead of [`Endpoint`][__link12] you now have to implement [`EndpointWithSchema`][__link13]. This means that some code might only compile on either feature, but not on both. If you are writing a library that uses gotham-restful, it is strongly recommended to pass both features through and conditionally enable the openapi code, like this: -However, please note that by default, the `without-openapi` feature of this crate is enabled. -Disabling it in favour of the `openapi` feature will add additional type bounds and method requirements -to some of the traits and types in this crate, for example instead of [`Endpoint`] you now have to -implement [`EndpointWithSchema`]. This means that some code might only compile on either feature, but not -on both. If you are writing a library that uses gotham-restful, it is strongly recommended to pass both -features through and conditionally enable the openapi code, like this: ```rust #[derive(Deserialize, Serialize)] @@ -367,8 +352,7 @@ features through and conditionally enable the openapi code, like this: struct Foo; ``` - [diesel]: https://diesel.rs/ - [`State`]: gotham::state::State + ## Versioning @@ -377,7 +361,7 @@ the MSRV (minimum supported rust version) is not considered a breaking change. ## License -Copyright (C) 2020-2021 Dominic Meiser and [contributors](https://github.com/msrd0/gotham_restful/graphs/contributors). +Copyright (C) 2020-2021 Dominic Meiser and [contributors]. ``` Licensed under the Apache License, Version 2.0 (the "License"); @@ -392,3 +376,19 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ``` + + [contributors]: https://github.com/msrd0/gotham_restful/graphs/contributors + [__link0]: https://crates.io/crates/gotham/0.6.0 + [__link1]: https://doc.rust-lang.org/stable/std/primitive.i64.html + [__link10]: https://docs.rs/gotham/0.6.0/gotham/?search=gotham::state::State + [__link11]: https://docs.rs/openapi_type/0.2.1/openapi_type/?search=openapi_type::OpenapiType + [__link12]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::endpoint::Endpoint + [__link13]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::endpoint::EndpointWithSchema + [__link2]: https://doc.rust-lang.org/stable/std/?search=std::string::String + [__link3]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::types::RequestBody + [__link4]: https://docs.rs/gotham/0.6.0/gotham/?search=gotham::extractor::QueryStringExtractor + [__link5]: https://docs.rs/gotham/0.6.0/gotham/?search=gotham::state::State + [__link6]: https://crates.io/crates/serde_json/1.0.64 + [__link7]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::response::Response::header + [__link8]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::cors::CorsRoute + [__link9]: https://diesel.rs/ diff --git a/crates-io.tpl b/crates-io.j2 similarity index 85% rename from crates-io.tpl rename to crates-io.j2 index 588eb25ac9..318e51bd09 100644 --- a/crates-io.tpl +++ b/crates-io.j2 @@ -9,7 +9,7 @@ the MSRV (minimum supported rust version) is not considered a breaking change. ## License -Copyright (C) 2020-2021 Dominic Meiser and [contributors](https://github.com/msrd0/gotham_restful/graphs/contributors). +Copyright (C) 2020-2021 Dominic Meiser and [contributors]. ``` Licensed under the Apache License, Version 2.0 (the "License"); @@ -24,3 +24,8 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ``` + + [contributors]: https://github.com/msrd0/gotham_restful/graphs/contributors +{%- if links != "" %} +{{ links }} +{%- endif -%} diff --git a/crates-io.md b/crates-io.md index 52c165383b..cbd45c9da7 100644 --- a/crates-io.md +++ b/crates-io.md @@ -1,46 +1,46 @@ # gotham-restful [![Rust 1.49+](https://img.shields.io/badge/rustc-1.49+-orange.svg)](https://blog.rust-lang.org/2020/12/31/Rust-1.49.0.html) [![License Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![GitHub](https://img.shields.io/badge/Code-On%20Github-blue?logo=GitHub)](https://github.com/msrd0/gotham_restful) -This crate is an extension to the popular [gotham web framework][gotham] for Rust. It allows you to -create resources with assigned endpoints that aim to be a more convenient way of creating handlers -for requests. +This crate is an extension to the popular [gotham web framework][__link0] for Rust. It allows you to create resources with assigned endpoints that aim to be a more convenient way of creating handlers for requests. + ## Features - Automatically parse **JSON** request and produce response bodies - Allow using **raw** request and response bodies - - Convenient **macros** to create responses that can be registered with gotham's router + - Convenient **macros** to create responses that can be registered with gotham’s router - Auto-Generate an **OpenAPI** specification for your API - - Manage **CORS** headers so you don't have to + - Manage **CORS** headers so you don’t have to - Manage **Authentication** with JWT - Integrate diesel connection pools for easy **database** integration + ## Safety -This crate is just as safe as you'd expect from anything written in safe Rust - and -`#![forbid(unsafe_code)]` ensures that no unsafe was used. +This crate is just as safe as you’d expect from anything written in safe Rust - and `#![forbid(unsafe_code)]` ensures that no unsafe was used. + ## Endpoints -There are a set of pre-defined endpoints that should cover the majority of REST APIs. However, -it is also possible to define your own endpoints. +There are a set of pre-defined endpoints that should cover the majority of REST APIs. However, it is also possible to define your own endpoints. + ### Pre-defined Endpoints Assuming you assign `/foobar` to your resource, the following pre-defined endpoints exist: -| Endpoint Name | Required Arguments | HTTP Verb | HTTP Path | -| ------------- | ------------------ | --------- | -------------- | -| read_all | | GET | /foobar | -| read | id | GET | /foobar/:id | -| search | query | GET | /foobar/search | -| create | body | POST | /foobar | -| update_all | body | PUT | /foobar | -| update | id, body | PUT | /foobar/:id | -| delete_all | | DELETE | /foobar | -| delete | id | DELETE | /foobar/:id | +| Endpoint Name | Required Arguments | HTTP Verb | HTTP Path | +| --- | --- | --- | --- | +| read_all | | GET | /foobar | +| read | id | GET | /foobar/:id | +| search | query | GET | /foobar/search | +| create | body | POST | /foobar | +| update_all | body | PUT | /foobar | +| update | id, body | PUT | /foobar/:id | +| delete_all | | DELETE | /foobar | +| delete | id | DELETE | /foobar/:id | + +Each of those endpoints has a macro that creates the neccessary boilerplate for the Resource. A simple example looks like this: -Each of those endpoints has a macro that creates the neccessary boilerplate for the Resource. A -simple example looks like this: ```rust /// Our RESTful resource. @@ -61,10 +61,11 @@ fn read(id: u64) -> Success { } ``` + ### Custom Endpoints -Defining custom endpoints is done with the `#[endpoint]` macro. The syntax is similar to that -of the pre-defined endpoints, but you need to give it more context: +Defining custom endpoints is done with the `#[endpoint]` macro. The syntax is similar to that of the pre-defined endpoints, but you need to give it more context: + ```rust use gotham_restful::gotham::hyper::Method; @@ -85,24 +86,22 @@ fn custom_endpoint(path: CustomPath) -> Success { } ``` + ## Arguments Some endpoints require arguments. Those should be - * **id** Should be a deserializable json-primitive like [`i64`] or [`String`]. - * **body** Should be any deserializable object, or any type implementing [`RequestBody`]. - * **query** Should be any deserializable object whose variables are json-primitives. It will - however not be parsed from json, but from HTTP GET parameters like in `search?id=1`. The - type needs to implement [`QueryStringExtractor`](gotham::extractor::QueryStringExtractor). -Additionally, all handlers may take a reference to gotham's [`State`]. Please note that for async -handlers, it needs to be a mutable reference until rustc's lifetime checks across await bounds -improve. + - **id** Should be a deserializable json-primitive like [`i64`][__link1] or [`String`][__link2]. + - **body** Should be any deserializable object, or any type implementing [`RequestBody`][__link3]. + - **query** Should be any deserializable object whose variables are json-primitives. It will however not be parsed from json, but from HTTP GET parameters like in `search?id=1`. The type needs to implement [`QueryStringExtractor`][__link4]. + +Additionally, all handlers may take a reference to gotham’s [`State`][__link5]. Please note that for async handlers, it needs to be a mutable reference until rustc’s lifetime checks across await bounds improve. + ## Uploads and Downloads -By default, every request body is parsed from json, and every respone is converted to json using -[serde_json]. However, you may also use raw bodies. This is an example where the request body -is simply returned as the response again, no json parsing involved: +By default, every request body is parsed from json, and every respone is converted to json using [serde_json][__link6]. However, you may also use raw bodies. This is an example where the request body is simply returned as the response again, no json parsing involved: + ```rust #[derive(Resource)] @@ -122,10 +121,11 @@ fn create(body : RawImage) -> Raw> { } ``` + ## Custom HTTP Headers -You can read request headers from the state as you would in any other gotham handler, and specify -custom response headers using [Response::header]. +You can read request headers from the state as you would in any other gotham handler, and specify custom response headers using [Response::header][__link7]. + ```rust #[derive(Resource)] @@ -143,10 +143,11 @@ async fn read_all(state: &mut State) -> NoContent { } ``` + ## Features -To make life easier for common use-cases, this create offers a few features that might be helpful -when you implement your web server. The complete feature list is +To make life easier for common use-cases, this create offers a few features that might be helpful when you implement your web server. The complete feature list is + - [`auth`](#authentication-feature) Advanced JWT middleware - `chrono` openapi support for chrono types - `full` enables all features except `without-openapi` @@ -157,16 +158,14 @@ when you implement your web server. The complete feature list is - `uuid` openapi support for uuid - `without-openapi` (**default**) disables `openapi` support. + ### Authentication Feature -In order to enable authentication support, enable the `auth` feature gate. This allows you to -register a middleware that can automatically check for the existence of an JWT authentication -token. Besides being supported by the endpoint macros, it supports to lookup the required JWT secret -with the JWT data, hence you can use several JWT secrets and decide on the fly which secret to use. -None of this is currently supported by gotham's own JWT middleware. +In order to enable authentication support, enable the `auth` feature gate. This allows you to register a middleware that can automatically check for the existence of an JWT authentication token. Besides being supported by the endpoint macros, it supports to lookup the required JWT secret with the JWT data, hence you can use several JWT secrets and decide on the fly which secret to use. None of this is currently supported by gotham’s own JWT middleware. A simple example that uses only a single secret looks like this: + ```rust #[derive(Resource)] #[resource(read)] @@ -203,14 +202,13 @@ fn main() { } ``` + ### CORS Feature -The cors feature allows an easy usage of this web server from other origins. By default, only -the `Access-Control-Allow-Methods` header is touched. To change the behaviour, add your desired -configuration as a middleware. +The cors feature allows an easy usage of this web server from other origins. By default, only the `Access-Control-Allow-Methods` header is touched. To change the behaviour, add your desired configuration as a middleware. + +A simple example that allows authentication from every origin (note that `*` always disallows authentication), and every content type, looks like this: -A simple example that allows authentication from every origin (note that `*` always disallows -authentication), and every content type, looks like this: ```rust #[derive(Resource)] @@ -236,18 +234,16 @@ fn main() { } ``` -The cors feature can also be used for non-resource handlers. Take a look at [`CorsRoute`] -for an example. +The cors feature can also be used for non-resource handlers. Take a look at [`CorsRoute`][__link8] for an example. + ### Database Feature -The database feature allows an easy integration of [diesel] into your handler functions. Please -note however that due to the way gotham's diesel middleware implementation, it is not possible -to run async code while holding a database connection. If you need to combine async and database, -you'll need to borrow the connection from the [`State`] yourself and return a boxed future. +The database feature allows an easy integration of [diesel][__link9] into your handler functions. Please note however that due to the way gotham’s diesel middleware implementation, it is not possible to run async code while holding a database connection. If you need to combine async and database, you’ll need to borrow the connection from the [`State`][__link10] yourself and return a boxed future. A simple non-async example looks like this: + ```rust #[derive(Resource)] #[resource(read_all)] @@ -277,16 +273,13 @@ fn main() { } ``` + ### OpenAPI Feature -The OpenAPI feature is probably the most powerful one of this crate. Definitely read this section -carefully both as a binary as well as a library author to avoid unwanted suprises. +The OpenAPI feature is probably the most powerful one of this crate. Definitely read this section carefully both as a binary as well as a library author to avoid unwanted suprises. + +In order to automatically create an openapi specification, gotham-restful needs knowledge over all routes and the types returned. `serde` does a great job at serialization but doesn’t give enough type information, so all types used in the router need to implement [`OpenapiType`][__link11]. This can be derived for almoust any type and there should be no need to implement it manually. A simple example looks like this: -In order to automatically create an openapi specification, gotham-restful needs knowledge over -all routes and the types returned. `serde` does a great job at serialization but doesn't give -enough type information, so all types used in the router need to implement -[`OpenapiType`](openapi_type::OpenapiType). This can be derived for almoust any type and there -should be no need to implement it manually. A simple example looks like this: ```rust #[derive(Resource)] @@ -319,18 +312,10 @@ fn main() { } ``` -Above example adds the resource as before, but adds two other endpoints as well: `/openapi` and `/`. -The first one will return the generated openapi specification in JSON format, allowing you to easily -generate clients in different languages without worying to exactly replicate your api in each of those -languages. The second one will return documentation in HTML format, so you can easily view your -api and share it with other people. +Above example adds the resource as before, but adds two other endpoints as well: `/openapi` and `/`. The first one will return the generated openapi specification in JSON format, allowing you to easily generate clients in different languages without worying to exactly replicate your api in each of those languages. The second one will return documentation in HTML format, so you can easily view your api and share it with other people. + +However, please note that by default, the `without-openapi` feature of this crate is enabled. Disabling it in favour of the `openapi` feature will add additional type bounds and method requirements to some of the traits and types in this crate, for example instead of [`Endpoint`][__link12] you now have to implement [`EndpointWithSchema`][__link13]. This means that some code might only compile on either feature, but not on both. If you are writing a library that uses gotham-restful, it is strongly recommended to pass both features through and conditionally enable the openapi code, like this: -However, please note that by default, the `without-openapi` feature of this crate is enabled. -Disabling it in favour of the `openapi` feature will add additional type bounds and method requirements -to some of the traits and types in this crate, for example instead of [`Endpoint`] you now have to -implement [`EndpointWithSchema`]. This means that some code might only compile on either feature, but not -on both. If you are writing a library that uses gotham-restful, it is strongly recommended to pass both -features through and conditionally enable the openapi code, like this: ```rust #[derive(Deserialize, Serialize)] @@ -338,8 +323,7 @@ features through and conditionally enable the openapi code, like this: struct Foo; ``` - [diesel]: https://diesel.rs/ - [`State`]: gotham::state::State + ## Versioning @@ -348,7 +332,7 @@ the MSRV (minimum supported rust version) is not considered a breaking change. ## License -Copyright (C) 2020-2021 Dominic Meiser and [contributors](https://github.com/msrd0/gotham_restful/graphs/contributors). +Copyright (C) 2020-2021 Dominic Meiser and [contributors]. ``` Licensed under the Apache License, Version 2.0 (the "License"); @@ -363,3 +347,19 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ``` + + [contributors]: https://github.com/msrd0/gotham_restful/graphs/contributors + [__link0]: https://crates.io/crates/gotham/0.6.0 + [__link1]: https://doc.rust-lang.org/stable/std/primitive.i64.html + [__link10]: https://docs.rs/gotham/0.6.0/gotham/?search=gotham::state::State + [__link11]: https://docs.rs/openapi_type/0.2.1/openapi_type/?search=openapi_type::OpenapiType + [__link12]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::endpoint::Endpoint + [__link13]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::endpoint::EndpointWithSchema + [__link2]: https://doc.rust-lang.org/stable/std/?search=std::string::String + [__link3]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::types::RequestBody + [__link4]: https://docs.rs/gotham/0.6.0/gotham/?search=gotham::extractor::QueryStringExtractor + [__link5]: https://docs.rs/gotham/0.6.0/gotham/?search=gotham::state::State + [__link6]: https://crates.io/crates/serde_json/1.0.64 + [__link7]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::response::Response::header + [__link8]: https://docs.rs/gotham_restful/0.4.0/gotham_restful/?search=gotham_restful::cors::CorsRoute + [__link9]: https://diesel.rs/ diff --git a/readme.sh b/readme.sh index 09f6bf6f29..1fa07f930e 100755 --- a/readme.sh +++ b/readme.sh @@ -14,7 +14,7 @@ for readme in README crates-io do output=$readme.md [ $check == y ] && output=$(mktemp) - cargo readme -t $readme.tpl -o $output + cargo doc2readme -t $readme.j2 -o $output if [ $check == y ] then diff $readme.md $output || ok=1 diff --git a/src/lib.rs b/src/lib.rs index 8c495cd819..6fc1e47761 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -513,7 +513,7 @@ pub use routing::{DrawResourceRoutes, DrawResources}; pub use routing::{DrawResourceRoutesWithSchema, DrawResourcesWithSchema, WithOpenapi}; mod types; -pub use types::*; +pub use types::{FromBody, RequestBody, ResponseBody}; /// This trait must be implemented for every resource. It allows you to register the different /// endpoints that can be handled by this resource to be registered with the underlying router. diff --git a/src/response/raw.rs b/src/response/raw.rs index c7ce993440..fa8655c6e3 100644 --- a/src/response/raw.rs +++ b/src/response/raw.rs @@ -1,5 +1,5 @@ use super::{handle_error, IntoResponse, IntoResponseError}; -use crate::{FromBody, RequestBody, ResourceType, Response}; +use crate::{types::ResourceType, FromBody, RequestBody, Response}; #[cfg(feature = "openapi")] use crate::{IntoResponseWithSchema, ResponseSchema}; #[cfg(feature = "openapi")]