Skip to content

Commit

Permalink
feat(doc): add doc about single property description (#444)
Browse files Browse the repository at this point in the history
  • Loading branch information
LeoTayot authored Jul 6, 2022
1 parent 43cfea1 commit 894428a
Showing 1 changed file with 4 additions and 0 deletions.
4 changes: 4 additions & 0 deletions book/actix-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,8 @@ use serde::{Serialize, Deserialize};
// Mark containers (body, query, parameter, etc.) like so...
#[derive(Serialize, Deserialize, Apiv2Schema)]
struct Pet {
// You can optionaly add description for an individual property with the following line
/// Name of the pet
name: String,
id: Option<i64>,
}
Expand Down Expand Up @@ -187,6 +189,8 @@ curl http://localhost:8080/api/spec/v2

Similarly, if we were to use other extractors like `web::Query<T>`, `web::Form<T>` or `web::Path`, the plugin will emit the corresponding specification as expected.

Description for an individual property uses Rust [doc comments](https://doc.rust-lang.org/reference/comments.html) technology.

#### Known limitations

- **Enums:** OpenAPI (v2) itself supports using simple enums (i.e., with unit variants), but Rust and serde has support for variants with fields and tuples. I still haven't looked deep enough either to say whether this can/cannot be done in OpenAPI or find an elegant way to represent this in OpenAPI.
Expand Down

0 comments on commit 894428a

Please sign in to comment.