From cb735bfd65aa148b4c5844751b5fff3c51e8b9fb Mon Sep 17 00:00:00 2001 From: Ravi Shankar Date: Sun, 29 Nov 2020 12:16:05 +0530 Subject: [PATCH] Update book --- book/README.md | 8 +++----- book/actix-operation-meta.md | 2 ++ book/actix-plugin.md | 1 + book/actix-schema-defaults.md | 3 ++- book/actix-security.md | 2 ++ book/actix-status-codes.md | 1 + book/cli.md | 2 +- book/compile-checks.md | 10 +++++----- 8 files changed, 17 insertions(+), 12 deletions(-) diff --git a/book/README.md b/book/README.md index b39f6c623..5fca59297 100644 --- a/book/README.md +++ b/book/README.md @@ -9,11 +9,9 @@ It's currently under active development and may not be ready for production use ### Features -**[Compile-time checking](build-script.md#compile-time-checks)**: See how paperclip checks parameters for API calls at compile time! - -**[Console checks](cli.md#runtime-checks)**: See how the console generated by paperclip checks API calls. - -**[Actix-web hosting](actix-plugin.md)**: See how paperclip can be used to host the API spec for your `actix-web` application. +- Paperclip CLI can generate API client library (which checks some usage at [compile-time](compile-checks.md)) or a console for your API (which checks usage at [runtime](cli.md#runtime-checks)). +- API client code can also be generated using [build scripts](build-script.md) which will then check parameters usage in your library at compile time. +- [Acix-web plugin](actix-plugin.md) can be used to host the API spec for your `actix-web` application. ### Design diff --git a/book/actix-operation-meta.md b/book/actix-operation-meta.md index 68206c499..8d8ec6dd0 100644 --- a/book/actix-operation-meta.md +++ b/book/actix-operation-meta.md @@ -1,3 +1,5 @@ +## Adding additional metadata to operations + By default, the first doc comment (if any) is taken for the `summary` field and the rest of the following doc comments (if any) will be taken as `description` for that operation. diff --git a/book/actix-plugin.md b/book/actix-plugin.md index 21340558f..d29d38d36 100644 --- a/book/actix-plugin.md +++ b/book/actix-plugin.md @@ -130,6 +130,7 @@ curl http://localhost:8080/api/spec "swagger": "2.0", "definitions": { "Pet": { + "type": "object", "properties": { "id": { "type": "integer", diff --git a/book/actix-schema-defaults.md b/book/actix-schema-defaults.md index 2c6d0e3b4..a04f5d9ae 100644 --- a/book/actix-schema-defaults.md +++ b/book/actix-schema-defaults.md @@ -1,9 +1,10 @@ +## Setting defaults in API schema It is possible to define default initial values for the schema, which might be useful to define "info", "schemes", "tags" and other top level schema fields which are not inherited from handlers. ```rust -use paperclip::v2::models::DefaultApiRaw; +use paperclip::v2::models::{DefaultApiRaw, Tag}; let mut spec = DefaultApiRaw::default(); spec.tags = vec![ diff --git a/book/actix-security.md b/book/actix-security.md index f00a3341e..017997688 100644 --- a/book/actix-security.md +++ b/book/actix-security.md @@ -1,3 +1,5 @@ +## Defining security schemes for your API + You can use `Apiv2Security` derive macro for structs which can then be used as handler parameters to have those handlers marked as requiring authorization. ```rust diff --git a/book/actix-status-codes.md b/book/actix-status-codes.md index ccf6a4af4..583aecef8 100644 --- a/book/actix-status-codes.md +++ b/book/actix-status-codes.md @@ -1,3 +1,4 @@ +## Adding additional response status codes to operations Paperclip deduces your API schema using macros (which read the types of handlers and parameter structs at compile time), so in order for paperclip to know what response code sent by the API, it needs type information about it at compile time. It cannot be inferred from response at runtime. diff --git a/book/cli.md b/book/cli.md index 0a51f4fb1..6d32a8ee9 100644 --- a/book/cli.md +++ b/book/cli.md @@ -94,7 +94,7 @@ GET http://echo.jsontest.com/pets/25 Passing `-v` flag enables verbose mode which prints additional information about the request we've made. Also note that the body of the response is piped to stdout directly. -### Request body +#### Request body Finally, let's `POST` something with a body. Here, `add-pet` requires a payload, so `--payload` argument is required. This argument is special in that it could be either a path to a file or `-` (when input is obtained from stdin). Either way, the input is parsed to the actual schema before making the API call. diff --git a/book/compile-checks.md b/book/compile-checks.md index c541840f5..a2046da9f 100644 --- a/book/compile-checks.md +++ b/book/compile-checks.md @@ -5,7 +5,7 @@ API calls often *require* some parameters. Should we miss those parameters when For example, in the [previous example](build-script.md), in order to fetch a pet, [`petId` parameter](https://github.com/wafflespeanut/paperclip/blob/fa95b023aaf8b6e396c899a93a9eda6fd791505c/openapi/tests/pet-v2.yaml#L42-L47) is required. Let's change the main function in the above example to fetch a pet without its ID. ```rust -let pet = Pet::get_pet_by_id().send(&client).compat().await?; +let pet = Pet::get_pet_by_id().send(&client).await?; ``` If we try and compile the program, then we'll get the following error: @@ -24,7 +24,7 @@ Hence the fix would be to set the required parameter using the relevant method c let pet = Pet::get_pet_by_id() .id(25) .send(&client) - .compat().await?; + .await?; ``` ... and the code will compile. @@ -34,7 +34,7 @@ The same applies to using API objects (with required fields). For example, the [ So, if we did this: ```rust -let pet = Pet::add_pet().send(&client).compat().await?; +let pet = Pet::add_pet().send(&client).await?; ``` ... we'd get an error during compilation: @@ -55,9 +55,9 @@ let pet = Pet::add_pet() .id(25) .name("Milo") .send(&client) - .compat().await?; + .await?; ``` ... and the code will compile. -> **NOTE:** The types of arguments are also enforced. +Similarly, the types of arguments are also enforced.