flowneee / okapi-operation Goto Github PK

It would be nice if we could serve the openapi both as yaml and json. This is commonly done by either using the Accept header, or by reading a format=[json|yaml] query parameter.

If there is 2 or more types with same name, they will override each other, when schema generated. For example

handler1.rs

#[derive(JsonSchema)]
struct Request {
    name: String
}

handler2.rs

#[derive(JsonSchema)]
struct Request {
    id: u64
}

will create only one definition in #/components/schema, and handlers from both files wil reference same schema.

First potenial fix - enable inlining in https://docs.rs/schemars/latest/schemars/gen/struct.SchemaSettings.html#structfield.inline_subschemas, which will solve most problems (probably everything sxcept recursive types).

Hi, would it be possible to default the operation_id to the handler method name?

Need to check all public API of this crate against https://rust-lang.github.io/api-guidelines/checklist.html, fixing all issues OR providing explanation for exceptions.

In the following scenario:

axum_integration::Router::new()
            .route(
                "/subscriptions",
                post(openapi_handler!(subscriptions::create_subscription)),
            )
            .route(
                "/subscriptions",
                get(openapi_handler!(subscriptions::list_subscriptions)),
            )

The latter route invocation will overwrite the former. This behavior is different from axum, as described here https://docs.rs/axum/latest/axum/struct.Router.html#accepting-multiple-methods

Example:

!10181 ➜ http -v GET localhost:8081/openapi Accept:application/yaml    
GET /openapi HTTP/1.1
Accept: application/yaml
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:8081
User-Agent: HTTPie/3.2.1



HTTP/1.1 400 Bad Request
content-length: 72
content-type: text/plain; charset=utf-8
date: Wed, 10 May 2023 08:06:34 GMT

Bad Accept header value, should be either 'json', 'yaml', '*/*' or empty

Seems like application/yaml (nor text/yaml) works. Both are used as yaml data types. application/json and text/json doesn't work either with same error.

Hi, I would like to be able to extract the specification generated by Router::route_openapi_specification without serving the contract, how can I do it? Could we split route_openapi_specification in two steps?

Hi, I was wondering if it's possible for a path to infer its documentation and summary from its rustdoc, in a similar fashion to how schemars does it: https://graham.cool/schemars/examples/6-doc_comments/

Current name originally was made to refer fact that crate provide macro to generate OpenAPI operation definition using okapi types.

Why name is not good:

• Some people might think that this crate related to okapi project (which is false);
• Almost immediately was added spec builder, implementations and integrations for axum (and potentially for different frameworks);
• There is possibility that this crate will move from okapi to something different (or maybe fork okapi), because okapi is designed to support OpenAPI 3.0, while there is 3.1 version which use JSON Schema draft 2020-12 for describing schemas, and as I understand okapi not planning to support different versions;
• Name is ugly)

So I think it would be good to have something neutral, not referring to any specific project or crate, and and general enough to include different instruments for building HTTP API specifications from code.

Currently project consist of 2 crates - main (okapi-operation) and proc-macro (okapi-operation-macro). I think it is good idea to split it into multiple crates

• -core: core types and traits (like ToResponses, ToMediaTypes) + impls for framework-specific types (like axum::extract::Json) under feature flags (because of orphanage rules)
• -<framework>: additional framework-specific things, for example for axum it could be Router replacement;
• -macro: proc-macro crate as is + framework-specific features under feature flags
• top-level crate: gather and expose all other crates with framework-specific feature under feature flags