deboa_bora/
lib.rs

1//! # bora - api Documentation
2//!
3//! Hello, and welcome to the bora API documentation!
4//!
5//! This API documentation is highly technical and is purely a reference.
6//!
7//! Depend on `bora` in `Cargo.toml`:
8//!
9//! ```toml
10//! [dependencies]
11//! bora = "0.0.1"
12//! ```
13//!
14//! <small>Note that development versions, tagged with `-dev`, are not published
15//! and need to be specified as [git dependencies].</small>
16//!
17//! ```rust,no_run
18//! use deboa::errors::DeboaError;
19//! use deboa_bora::bora;
20//! use vamo::Vamo;
21//!
22//! use serde::Deserialize;
23//!
24//! #[derive(Deserialize, Debug)]
25//! pub struct Post {
26//!     pub id: u32,
27//!     pub title: String,
28//! }
29//!
30//! #[bora(
31//!     api(
32//!         get(name="get_all", path="/posts", res_body=Vec<Post>, format="json"),
33//!         get(name="get_by_id", path="/posts/<id:i32>", res_body=Post, format="json"),
34//!         get(name="query_by_id", path="/posts?<id:i32>", res_body=Vec<Post>, format="json"),
35//!         get(name="query_by_title", path="/posts?<id:i32>&<title:&str>", res_body=Vec<Post>, format="json")
36//!     )
37//! )]
38//! pub struct PostService;
39//!
40//! #[tokio::main]
41//! async fn main() -> Result<()> {
42//!     let client = Vamo::new("https://jsonplaceholder.typicode.com")?;
43//!
44//!     let mut post_service = PostService::new(client);
45//!
46//!     let post = post_service.get_by_id(1).await?;
47//!
48//!     println!("id...: {}", post.id);
49//!     println!("title: {}", post.title);
50//!
51//!     assert_eq!(post.id, 1);
52//!     Ok(())
53//! }
54//! ```
55//!
56//! Disabled features can be selectively enabled in `Cargo.toml`:
57//!
58//! ```toml
59//! [dependencies]
60//! bora = { version = "0.0.1", features = ["tokio_rt", "http1", "http2"] }
61//! vamo = { version = "0.0.1" }
62//! deboa-extras = { version = "0.0.1" }
63//! ```
64//!
65
66use proc_macro::TokenStream;
67
68mod bora;
69mod parser;
70mod token;
71
72use crate::bora::api::bora as bora_macro;
73
74#[proc_macro_attribute]
75///
76/// The `bora` attribute macro is used to generate a Deboa client.
77/// With this macro you can define the API endpoints and their methods.
78/// You can define multiple endpoints and methods in the same macro.
79///
80/// A basic definition is:
81///
82/// #[bora(api(operation)))]
83///
84/// Where 'operation' is one or more of the following:
85///
86/// - get
87/// - post
88/// - delete
89/// - put
90/// - patch
91///
92/// # get
93///
94/// The `get` operation is used to retrieve data from the API.
95///
96/// It has the following arguments:
97///
98/// - name: The name of the operation.
99/// - path: The path of the operation.
100/// - res_body: The type of the response body.
101/// - format: The format of the response body.
102///
103/// ## Example
104///
105/// ```compile_fail
106/// #[bora(api(get(name = "get_post", path = "/posts/<id:i32>")))]
107/// pub struct PostService;
108/// ```
109///
110/// # post
111///
112/// The `post` operation is used to create data in the API.
113///
114/// It has the following arguments:
115///
116/// - name: The name of the operation.
117/// - path: The path of the operation.
118/// - req_body: The type of the request body.
119/// - res_body: The type of the response body.
120/// - format: The format of the response body.
121///
122/// ## Example
123///
124/// ```compile_fail
125/// #[bora(api(post(name = "post_post", path = "/posts", req_body = "Post", res_body = "Post")))]
126/// pub struct PostService;
127/// ```
128///
129/// # delete
130///
131/// The `delete` operation is used to delete data from the API.
132///
133/// It has the following arguments:
134///
135/// - name: The name of the operation.
136/// - path: The path of the operation.
137///
138/// ## Example
139///
140/// ```compile_fail
141/// #[bora(api(delete(name = "delete_post", path = "/posts/<id:i32>")))]
142/// pub struct PostService;
143/// ```
144///
145/// # put
146///
147/// The `put` operation is used to update data in the API.
148///
149/// It has the following arguments:
150///
151/// - name: The name of the operation.
152/// - path: The path of the operation.
153/// - req_body: The type of the request body.
154/// - res_body: The type of the response body.
155/// - format: The format of the response body.
156///
157/// ## Example
158///
159/// ```compile_fail
160/// #[bora(api(put(name = "put_post", path = "/posts/<id:i32>", req_body = "Post", res_body = "Post")))]
161/// pub struct PostService;
162/// ```
163///
164/// # patch
165///
166/// The `patch` operation is used to update data in the API.
167///
168/// It has the following arguments:
169///
170/// - name: The name of the operation.
171/// - path: The path of the operation.
172/// - req_body: The type of the request body.
173/// - res_body: The type of the response body.
174/// - format: The format of the response body.
175///
176/// ## Example
177///
178/// ```compile_fail
179/// #[bora(api(patch(name = "patch_post", path = "/posts/<id:i32>", req_body = "Post", res_body = "Post")))]
180/// pub struct PostService;
181/// ```
182pub fn bora(attr: TokenStream, item: TokenStream) -> TokenStream {
183    bora_macro(attr, item)
184}
deboa_bora/lib.rs

deboa_bora/
lib.rs
