.github/workflows/ci.yml

@@ -6,64 +6,31 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  check:
-    name: Check
+  clippy:
+    name: Run linter
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-      - uses: actions-rs/cargo@v1
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
         with:
-          command: check
-          args: --all-features
+          components: clippy
+      - run: cargo clippy --all-features -- -D warnings
 
-  test:
-    name: Test Suite
+  # TODO: add coverage
+  test_cov:
+    name: Run tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-      - uses: actions-rs/cargo@v1
-        with:
-          command: test
-          args: --all-features
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo test --all-features
 
   fmt:
-    name: Rustfmt
+    name: Check code formatting
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-      - run: rustup component add rustfmt
-      - uses: actions-rs/cargo@v1
-        with:
-          command: fmt
-          args: --all -- --check
-
-  clippy:
-    name: Clippy
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-      - run: rustup component add clippy
-      - uses: actions-rs/cargo@v1
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
         with:
-          command: clippy
-          args: --all-features -- -D warnings
+          components: rustfmt
+      - run: cargo fmt --all -- --check

.gitignore

@@ -1,2 +1,3 @@
 /target
+.idea
 Cargo.lock

Cargo.toml

@@ -1,5 +1,7 @@
 [workspace]
+resolver = "2"
 members = [
     "./okapi-operation-macro",
-    "./okapi-operation"
+    "./okapi-operation",
+    "./okapi-examples"
 ]

README.md

@@ -4,11 +4,12 @@
 [![docs.rs](https://img.shields.io/docsrs/okapi-operation/latest)](https://docs.rs/okapi-operation/latest)
 ![CI](https://github.com/Flowneee/okapi-operation/actions/workflows/ci.yml/badge.svg)
 
-Library which allow to generate OpenAPI's operation definitions (using types from `okapi` crate) with procedural macro `#[openapi]`.
+Library which allow to generate OpenAPI's operation definitions (using types from `okapi` crate) with procedural
+macro `#[openapi]`.
 
 ## Example (with axum-integration feature).
 
-```rust,compile
+```rust,no_run
 use axum::{extract::Query, Json};
 use okapi_operation::{axum_integration::*, *};
 use serde::Deserialize;
@@ -38,35 +39,32 @@ async fn echo_get(query: Query<Request>) -> Json<String> {
     tags = "echo"
 )]
 async fn echo_post(
-    #[request_body(description = "Echo data", required = true)] body: Json<Request>,
+    #[body(description = "Echo data", required = true)] body: Json<Request>,
 ) -> Json<String> {
     Json(body.0.data)
 }
 
 fn main() {
-    // Here you can also add security schemes, other operations, modify internal OpenApi object.
-    let oas_builder = OpenApiBuilder::new("Demo", "1.0.0");
-    
     let app = Router::new()
         .route("/echo/get", get(openapi_handler!(echo_get)))
         .route("/echo/post", post(openapi_handler!(echo_post)))
-        .route_openapi_specification("/openapi", oas_builder)
+        .finish_openapi("/openapi", "Demo", "1.0.0")
         .expect("no problem");
-
-    let fut = async {
-        axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
-            .serve(app.into_make_service())
-            .await
-            .unwrap();
-    };
-    //tokio::runtime::Runtime::new().block_on(fut);
+    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
+    axum::serve(listener, app.into_make_service()).await.unwrap()
 }
 ```
 
 ## Features
 
 * `macro`: enables re-import of `#[openapi]` macro (enabled by default);
-* `axum-integration`: enables integration with `axum`(https://github.com/tokio-rs/axum) crate (implement traits for certain `axum` types).
+* `axum-integration`: enables integration with `axum`(https://github.com/tokio-rs/axum) crate (implement traits for
+  certain `axum` types):
+    * Compatibility with `axum`: since integration heavely rely on `axum` types, this crate will be compatible only with
+      few (maybe even one) last versions of `axum`;
+    * Currently supported `axum` versions: `0.7.x`.
+* `yaml`: enables ability to serve the spec in yaml format in case of present `Accept` header with `yaml` value.
+  Otherwise, in case of values `json|*/*` or empty, `json`'s being served (currently affects only `axum-integration`).
 
 ## TODO
 

okapi-examples/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "okapi-examples"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+axum = "0.7"
+axum-extra = { version = "0.9", features = ["typed-header"] }
+tokio = { version = "1", features = ["full"] }
+serde = { version = "1", features = ["derive"] }
+okapi-operation = { path = "../okapi-operation", features = ["axum", "yaml"] }
+okapi-operation-macro = { path = "../okapi-operation-macro", features = ["axum"] }

okapi-examples/src/main.rs

@@ -0,0 +1,60 @@
+use axum::{extract::Query, Json};
+use okapi_operation::{axum_integration::*, *};
+use serde::Deserialize;
+
+#[derive(Deserialize, JsonSchema)]
+struct Request {
+    /// Echo data
+    data: String,
+}
+
+#[openapi(
+    summary = "Echo using GET request",
+    operation_id = "echo_get",
+    tags = "echo",
+    parameters(
+        query(name = "echo-data", required = true, schema = "std::string::String",),
+        header(name = "x-request-id", schema = "std::string::String",),
+        header(name = "Accept", schema = "std::string::String")
+    )
+)]
+async fn echo_get(query: Query<Request>) -> Json<String> {
+    Json(query.0.data)
+}
+
+#[openapi(
+    summary = "Echo using POST request",
+    operation_id = "echo_post",
+    tags = "echo"
+)]
+async fn echo_post(
+    #[body(description = "Echo data", required = true)] body: Json<Request>,
+) -> Json<String> {
+    Json(body.0.data)
+}
+
+// Detect schema from known types, Json in this case
+#[openapi(
+    summary = "Echo using PUT request",
+    operation_id = "echo_put",
+    tags = "echo"
+)]
+async fn echo_put(body: Json<Request>) -> Json<String> {
+    Json(body.0.data)
+}
+
+#[tokio::main]
+async fn main() {
+    let app = Router::new()
+        .route(
+            "/echo",
+            get(oh!(echo_get)).post(oh!(echo_post)).put(oh!(echo_put)),
+        )
+        .finish_openapi("/openapi", "Demo", "1.0.0")
+        .expect("no problem");
+
+    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
+    axum::serve(listener, app.into_make_service())
+        .await
+        .unwrap()
+}

okapi-operation-macro/CHANGELOG.md

@@ -3,6 +3,34 @@ All notable changes to this project will be documented in the changelog of the r
 This project follows the [Semantic Versioning standard](https://semver.org/).
 
 
+## [0.2.0] - 2024-08-07
+### Added
+ - Feature `axum` for enable axum-specific functionality;
+ - Request body detection from function arguments for specific frameworks (i.e. axum);
+ - `#[body]` attribute as replacement for `#[request_body]` (now considered deprecated);
+ - Updates `syn` crate to version 2;
+ - `crate` attribute to support renaming base crate, by default `okapi_operation`;
+ - `#[openapi]` macro takes care of reimporting necessary types and traits from base crate.
+
+### Removed
+ - Support for multiple `#[openapi]` appearances above function.
+
+
+## [0.1.4] - 2024-07-18
+### Changed
+ - `#[request_body]` attribute can be used without braces.
+
+
+## [0.1.3] - 2023-04-29
+### Changed
+ - `axum` bumped to `0.6`.
+
+
+## [0.1.2] - 2023-03-07
+### Changed
+ - Used version 0.14.3 of `darling`.
+
+
 ## [0.1.1] - 2022-08-06
 ### Added
  - Cookie parameters.

okapi-operation-macro/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "okapi-operation-macro"
 description = "Macro implementation for okapi-operation"
-version = "0.1.1"
+version = "0.2.0"
 authors = ["Andrey Kononov flowneee3@gmail.com"]
 edition = "2021"
 license = "MIT"
@@ -14,13 +14,15 @@ repository = "https://github.com/Flowneee/okapi-operation"
 proc-macro = true
 
 [dependencies]
-darling = "0.13"
-lazy_static = "1.4"
+darling = "0.20"
+lazy_static = "1"
 proc-macro2 = "1"
 quote = "1"
-syn = { version = "1", features = ["full"] }
+syn = { version = "2", features = ["full"] }
 thiserror = "1"
 
+[features]
+axum = []
+
 [dev-dependencies]
-axum = "0.5"
-okapi = { version = "0.7.0-rc.1", features = ["preserve_order"] }
+assert_matches = "1"

okapi-operation-macro/src/error.rs

@@ -1,6 +1,6 @@
 use std::fmt::Display;
 
-use proc_macro2::TokenStream;
+use proc_macro2::{Span, TokenStream};
 use quote::ToTokens;
 
 #[derive(Debug, thiserror::Error)]
@@ -9,6 +9,8 @@ pub(crate) enum Error {
     Syn(#[from] syn::Error),
     #[error(transparent)]
     Darling(#[from] darling::Error),
+    #[error("{0}")]
+    Custom(String),
 }
 
 impl Error {
@@ -20,6 +22,11 @@ impl Error {
         match self {
             Error::Syn(x) => x.into_compile_error(),
             Error::Darling(x) => x.write_errors(),
+            Error::Custom(x) => syn::Error::new(Span::call_site(), x).into_compile_error(),
         }
     }
+
+    pub(crate) fn custom(message: impl Into<String>) -> Self {
+        Self::Custom(message.into())
+    }
 }

okapi-operation-macro/src/lib.rs

@@ -1,4 +1,6 @@
-use syn::{parse_macro_input, AttributeArgs, ItemFn};
+#![allow(clippy::manual_unwrap_or_default)]
+
+use syn::{parse_macro_input, ItemFn};
 
 mod error;
 mod operation;
@@ -11,10 +13,7 @@ pub fn openapi(
     attr: proc_macro::TokenStream,
     input: proc_macro::TokenStream,
 ) -> proc_macro::TokenStream {
-    match operation::openapi(
-        parse_macro_input!(attr as AttributeArgs),
-        parse_macro_input!(input as ItemFn),
-    ) {
+    match operation::openapi(attr, parse_macro_input!(input as ItemFn)) {
         Ok(x) => x.into(),
         Err(err) => err.write().into(),
     }