[oapi] swagger path

[josejachuf]

Hi, how are you?

I have an API with Openopi documentation using utoipa in this way [1]

I am now trying to use the integration of Salvo-Openopi, but I am failing on the route to Swagger.

In http://127.0.0.1:7887/api-doc/openapi.json I get correctly:

{
  "openapi": "3.1.0",
  "info": {
    "title": "TEST API",
    "version": "0.0.1"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "my_app::health::get_health",
        "responses": {}
      }
    },
    "/health": {
      "get": {
        "operationId": "my_app::health::get_health",
        "responses": {}
      }
    },
    "/version": {
      "get": {
        "operationId": "my_app::version::get_version",
        "responses": {}
      }
    }
  }
}

but in http://127.0.0.1:7887/swagger-ui/ I get 404 error

My router tree is:

fn router(config: &Config) -> Router {
    let cache_20s = Cache::new(
        MemoryStore::builder()
            .time_to_live(Duration::from_secs(20))
            .build(),
        RequestIssuer::default(),
    );

    let cors_handler = Cors::new()
        .allow_origin(cors::Any)
        // .allow_origin(AllowOrigin::any())
        .allow_methods(vec![Method::GET,
                            Method::POST,
                            Method::DELETE,
                            Method::OPTIONS,
                            ])
         .allow_headers(vec![
            "CONTENT-TYPE",
            "content-type",
            "Access-Control-Request-Method",
            "Access-Control-Allow-Origin",
            "Access-Control-Allow-Headers",
            "Access-Control-Max-Age",
            "authorization",
            "Authorization",
        ])
        .into_handler();

    let router = Router::new()
        .hoop(Logger::default())
        .get(health::get_health)
        .push(Router::with_path("health").get(health::get_health))
        .push(Router::with_path("version").get(version::get_version))
        // .push(Router::with_path("api-doc/openapi.json").get(openapi::openapi_json))
        // .push(Router::with_path("/swagger-ui/<**>").get(openapi::serve_swagger))
        .push(
            Router::with_hoop(affix::inject(config.clone()))
                .hoop(auth::auth_handler(config.clone().secret_key))
                .push(
                    Router::with_path("graphql")
                        .hoop(auth::validate_token)
                        .hoop(affix::insert("app_name", "API-GRAPHQL"))
                        .hoop(affix::insert("role_name", "lectura"))
                        .hoop(auth::validate_app_role)
                        .post(graphql::main::graphql),
                )
                .push(Router::with_path("playground").get(graphql::main::playground))
                .push(Router::with_path("graphiql").get(graphql::main::graphiql))
                .push(
                    Router::with_path("api/v1")
                        .hoop(auth::validate_token)
                        .hoop(cache_20s)                       
                        .push(
                            Router::with_path("<**rest>")
                                .hoop(cors_handler)
                                .options(handler::empty()),
                        ),
                ),
        );

    let doc = OpenApi::new("TEST API", "0.0.1").merge_router(&router);

    let router = router
        .push(doc.into_router("/api-doc/openapi.json"))
        .push(SwaggerUi::new("/api-doc/openapi.json").into_router("/"));
    println!("router: {:?}", router);
    println!("SwaggerUi: {:?}", SwaggerUi::new("/api-doc/openapi.json").into_router("/"));
    router

}

router: └──!NULL!
├──[GET] -> my_app::health::get_health
├──health
│ └──[GET] -> my_app::health::get_health
├──version
│ └──[GET] -> my_app::version::get_version
├──!NULL!
│ ├──graphql
│ │ └──[POST] -> my_app::graphql::main::graphql
│ ├──playground
│ │ └──[GET] -> my_app::graphql::main::playground
│ ├──graphiql
│ │ └──[GET] -> my_app::graphql::main::graphiql
│ └──api/v1
│ └──<rest>
│ └──[OPTIONS] -> salvo_core::handler::EmptyHandler
├──/api-doc/openapi.json -> salvo_oapi::openapi::OpenApi
└──//<> -> salvo_oapi::swagger_ui::SwaggerUi

What do I have bad?

[1] https://github.com/salvo-rs/salvo/tree/main/examples/todos-utoipa

[chrislearn]

It seems you attached your Swagger UI to http://127.0.0.1:7887/

[josejachuf]

Hi @chrislearn

No, the route http://127.0.0.1:7887/ directs to my_app::health::get_health

[josejachuf]

I simplified and cleaned the router function, but I still get the 404

fn router(config: &Config) -> Router {

    let router = Router::new()
        .hoop(Logger::default())
        .get(health::get_health)
        .push(Router::with_path("health").get(health::get_health))
        .push(Router::with_path("version").get(version::get_version));

    let doc = OpenApi::new("TEST API", "0.0.1").merge_router(&router);

    let router = router
        .push(doc.into_router("/api-doc/openapi.json"))
        .push(SwaggerUi::new("/api-doc/openapi.json").into_router("/"));
    router
}

[chrislearn]

Try this and access http://127.0.0.1:7887/swagger-ui/:

fn router(config: &Config) -> Router {

    let router = Router::new()
        .hoop(Logger::default())
        .get(health::get_health)
        .push(Router::with_path("health").get(health::get_health))
        .push(Router::with_path("version").get(version::get_version));

    let doc = OpenApi::new("TEST API", "0.0.1").merge_router(&router);

    let router = router
        .push(doc.into_router("/api-doc/openapi.json"))
        .push(SwaggerUi::new("/api-doc/openapi.json").into_router("/swagger-ui"));
    router
}

[josejachuf]

This works fine!!

Thanks

[josejachuf]

Some things are interesting:

• The explicit return data type and/or Result ("Response" is not needed)
• When using extractors "Request" is not needed

Can extractors also use with #[handler]?

Any doubts:

How is "status_codes" used?
What does #[endpoint (status_codes (200, 204, 409))] mean? Are all the potential status_codes that can return?

When I used Utoipa "by hand" I could put the path explicitly:

#[utoipa::path(
    get,
    path = "/api/v1/customers/{id}?key=ABC",
...
)

Now I put it as docstrings
Is it possible to define the path so that it appears next to the "GET" button for example?

[chrislearn]

Can extractors also use with #[handler]?
Yes, you can, change #[endpoint] to #[handler], it still works, just ignored when generate openapi data.

How is "status_codes" used?
What does #[endpoint (status_codes (200, 204, 409))] mean? Are all the potential status_codes that can return?
"status_codes" is a filter, it just said this endpoint's only has these status code. For example: fn handler()->Result<(), StatusError>. if you do not write status_codes, all status codes(100, 200, 301, 404, 500, ...) will be generated in openapi json.

Is it possible to define the path so that it appears next to the "GET" button for example?
Salvo scan router and get path information automatic, you can not put the path explicitly. But you can give the path a prefix globally, this may useful when you use nginx as proxy and url rewrite. https://docs.rs/salvo-oapi/latest/salvo_oapi/struct.OpenApi.html#method.merge_router_with_base.

[josejachuf]

Thanks very much!!!