utoipauto - GitLite

KO | EN

gitlite — search

#javascript #typescript #llm #go #android #nodejs #macos #java #windows #awesome #vue #security #ios #mcp

utoipauto

(★ 196)

Rust Macros to automate the addition of Paths/Schemas to Utoipa crate, simulating Reflection during the compilation phase

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - publish.yml
- - Cargo.toml
- - Cargo.toml
- - Cargo.toml
- - Cargo.toml
- - Cargo.toml
- .editorconfig
- Cargo.lock
- Cargo.toml
- LICENSE-APACHE
- LICENSE-MIT
- README.md
- rustfmt.toml
- - lib.rs
- - test.rs
- Cargo.toml
- - attribute_utils.rs
  - discover.rs
  - file_utils.rs
  - lib.rs
  - pair.rs
  - string_utils.rs
  - token_utils.rs
- Cargo.toml
- - lib.rs
- Cargo.toml
.editorconfig
.gitignore
armory.toml
Cargo.toml
LICENSE-APACHE
LICENSE-MIT
README.md
rustfmt.toml

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/ProbablyClem/utoipauto

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd utoipauto

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Rust

보통 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Rust (rustup) rustup으로 설치하면 cargo도 함께 설치됩니다.

cargo add utoipauto

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ cargo build가 에러 없이 끝나면 성공입니다. target/ 폴더에 실행 파일이 생성됩니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div style="text-align: center">
<h1>Utoipauto</h1>
  <p>
    <strong>Rust Macros to automate the addition of Paths/Schemas to Utoipa crate, simulating Reflection during the compilation phase</strong>
  </p>
</div>

# Crate presentation

Utoipa is a great crate for generating documentation (openapi/swagger) via source code.

But since Rust is a static programming language, we don't have the possibility of automatically discovering paths and
dto in runtime and adding them to the documentation,

For APIs with just a few endpoints, it's not that much trouble to add controller functions one by one, and DTOs one by
one.

But, if you have hundreds or even thousands of endpoints, the code becomes very verbose and difficult to maintain.

Ex :

```rust

#[derive(OpenApi)]
#[openapi(
    paths(
        // <================================ All functions  1 to N
        test_controller::service::func_get_1,
        test_controller::service::func_get_2,
        test_controller::service::func_get_3,
        test_controller::service::func_get_4,
       ....
       ....
       ....
        test_controller::service::func_get_N,

),
    components(
        // <====================== All DTO one by one
        schemas(TestDTO_1,  TestDTO_2, ........ , TestDTO_N)
    ),
    tags(
        (name = "todo", description = "Todo management endpoints.")
    ),
    modifiers(&SecurityAddon)
)]
pub struct ApiDoc;

```

The goal of this crate is to propose a macro that automates the detection of methods carrying Utoipa
macros (`#[utoipa::path(...]`), and adds them automatically. (it also detects sub-modules.)

It also detects struct that derive or implement `ToSchema` for the `components(schemas)` section, and the `ToResponse`
for the `components(responses)` section.

# Features

- [x] Automatic recursive path detection
- [x] Automatic import from module
- [x] Automatic import from src folder
- [x] Automatic model detection
- [x] Automatic response detection
- [x] Works with workspaces
- [x] Exclude a method from automatic scanning
- [x] Custom path detection

# How to use it

Simply add the crate `utoipauto` to the project

```
cargo add utoipauto
```

Import macro

```rust
use utoipauto::utoipauto;
```

Then add the `#[utoipauto]` macro just before the #[derive(OpenApi)] and `#[openapi]` macros.

## Important !!

Put `#[utoipauto]` before `#[derive(OpenApi)] `and `#[openapi]` macros.

```rust
#[utoipauto(paths = "MODULE_SRC_FILE_PATH, MODULE_SRC_FILE_PATH, ...")]
```

The paths receives a String which must respect this structure :

`"MODULE_SRC_FILE_PATH, MODULE_SRC_FILE_PATH, ..."`

You can add several paths by separating them with a coma `","`.

## Usage with workspaces

If you are using a workspace, you must specify the name of the crate in the path.
<br>
This applies even if you are using `#[utoipauto]` in the same crate.

```rust
#[utoipauto(paths = "./utoipauto/src")]
```

You can specify that the specified paths are from another crate by using the from key work.

```rust
#[utoipauto(paths = "./utoipauto/src from utoipauto")]
```

### Import from src folder

If no path is specified, the macro will automatically scan the `src` folder and add all the methods carrying
the `#[utoipa::path(...)]` macro, and all structs deriving `ToSchema` and `ToResponse`.
Here's an example of how to add all the methods contained in the src code.

```rust
...

use utoipauto::utoipauto;

...
#[utoipauto]
#[derive(OpenApi)]
#[openapi(
    tags(
        (name = "todo", description = "Todo management endpoints.")
    ),
    modifiers(&SecurityAddon)
)]

pub struct ApiDoc;

...

```

### Import from module

Here's an example of how to add all the methods and structs contained in the rest module.

```rust

use utoipauto::utoipauto;

#[utoipauto(
    paths = "./src/rest"
)]
#[derive(OpenApi)]
#[openapi(
    tags(
        (name = "todo", description = "Todo management endpoints.")
    ),
    modifiers(&SecurityAddon)
)]

pub struct ApiDoc;

```

Here's an example of how to add all methods and structs contained in the rest module if it is in a sub-folder:

```rust

use utoipauto::utoipauto;

#[utoipauto(
    paths = "(./src/lib/rest from crate::rest)"
)]
#[derive(OpenApi)]
#[openapi(
    tags(
        (name = "todo", description = "Todo management endpoints.")
    ),
    modifiers(&SecurityAddon)
)]

pub struct ApiDoc;

```

### Import from filename

Here's an example of how to add all the methods contained in the test_controller and test2_controller modules.
you can also combine automatic and manual addition, as here we've added a method manually to the documentation "
other_controller::get_users", and a schema "TestDTO".

```rust

use utoipauto::utoipauto;

#[utoipauto(
    paths = "./src/rest/test_controller.rs,./src/rest/test2_controller.rs "
)]
#[derive(OpenApi)]
#[openapi(
    paths(

crate::rest::other_controller::get_users,
    ),
    components(
        schemas(TestDTO)
    ),
    tags(
        (name = "todo", description = "Todo management endpoints.")
    ),
    modifiers(&SecurityAddon)
)]

pub struct ApiDoc;

```

## Exclude a method from automatic scanning

you can exclude a function from the Doc Path list by adding the following macro `#[utoipa_ignore]` .

ex:

```rust
    /// Get all pets from database
///
#[utoipa_ignore]  //<============== this Macro
#[utoipa::path(
    responses(
            (status = 200, description = "List all Pets", body = [ListPetsDTO])
    )
)]
#[get("/pets")]
async fn get_all_pets(req: HttpRequest, store: web::Data<AppState>) -> impl Responder {
    // your CODE
}

```

## Exclude a struct from automatic scanning

you can also exclude a struct from the models and reponses list by adding the following macro `#[utoipa_ignore]` .

ex:

```rust
    #[utoipa_ignore]  //<============== this Macro
#[derive(ToSchema)]
struct ModelToIgnore {
    // your CODE
}

```

## Exclude files from scanning

You can exclude files and directories from discovery with the `exclude`
attribute, which takes a list of glob patterns.

```rust
#[utoipauto(paths = "./src", exclude = ["**/generated/**", "**/*_test.rs"])]
#[derive(OpenApi)]
#[openapi(tags())]
pub struct ApiDoc;
```

Patterns are matched against each candidate path and support `*`, `**`, `?`,
and brace alternation such as `**/*_{test,gen}.rs` (see the
[`globset`](https://docs.rs/globset) syntax).

`exclude` defaults to `["**/._*"]`. Those are AppleDouble sidecar files that
macOS writes next to sources on filesystems without extended-attribute support
(exFAT, FAT32, many network shares); they mirror the `.rs` extension but hold a
binary payload, so scanning them fails. Passing `exclude` replaces the default,
so include `**/._*` yourself if you still want those skipped:

```rust
#[utoipauto(exclude = ["**/._*", "**/generated/**"])]
```

Passing an empty list disables exclusion entirely:

```rust
#[utoipauto(exclude = [])]
```

### Custom path detection

By default, this macro will look for function with the `#[utoipa::path(...)]` attribute, but you can also specify a
custom attribute to look for.

```rust
#[handler]
pub fn custom_router() {
    // ...
}

#[utoipauto(function_attribute_name = "handler")] //Custom attribute
#[derive(OpenApi)]
#[openapi(tags()))]
pub struct ApiDoc;

```

You can also specify custom attributes for the model and response detection.

```rust
#[derive(Schema, Response)]
pub struct CustomModel {
    // ...
}

#[utoipauto(schema_attribute_name = "Schema", response_attribute_name = "Response")] //Custom derive
#[derive(OpenApi)]
#[openapi(tags())]
pub struct ApiDoc;

```

## Note

Sub-modules within a module containing methods tagged with utoipa::path are also automatically detected.

## Contributing

Contributions are welcomed, feel free to submit a PR or an issue.

## Inspiration

Inspired by [utoipa_auto_discovery](https://github.com/rxdiscovery/utoipa_auto_discovery)