Retrieve OpenApi object after generating

[ralpha]

Currently there is no easy way to get the OpenApi object or the generated file without starting rocket.

I made a small (hacky) workaround to get the OpenApi object without starting rocket.
Here are some code snippets if someone has the same issue. But it would be code if this was supported in the crate.

Somewhere in my code:

pub fn get_openapi() -> OpenApi{
    generate_openapi_file![
        //...add all calls that are also inside `routes_with_openapi`..
    ]
}

Rocket_okapi_codegen/src/lib.rs

#[proc_macro]
pub fn generate_openapi_file(input: TokenStream) -> TokenStream {
    routes_with_openapi::parse_openapi_file(input)
}

Rocket_okapi_codegen/src/routes_with_openapi/mod.rs

pub fn parse_openapi_file(routes: TokenStream) -> TokenStream {
    get_openapi_file(routes)
        .unwrap_or_else(|e| e.to_compile_error())
        .into()
}

// Basically a modified `parse_inner` with some small changes 
// (there is some custom code like `get_new_openapi_object` here)
fn get_openapi_file(routes: TokenStream) -> Result<TokenStream2>{
    let paths = <Punctuated<Path, Comma>>::parse_terminated.parse(routes)?;
    let add_operations = create_add_operations(paths)?;
    let openapi_object = get_new_openapi_object();
    Ok(quote! {
        {
            let settings = ::rocket_okapi::settings::OpenApiSettings::new();
            let mut gen = ::rocket_okapi::gen::OpenApiGenerator::new(settings.clone());
            #add_operations
            #openapi_object
            // It does not return the routes here, but the spec instead.
            spec
        }
    })
}

Like I said this is a bit of a hack. But a native way would be nice.

[nathanielford]

Out of curiosity, what's the chance that this (or something like it) could be applied in a build.rs build script? I am still pretty new to Rust and, since I am not quite able to parse out all of what okapi is doing to generate the file, I suspect that full compilation might be needed for the api spec to be created (specifically because custom data type de/serialization would need to be computed)? And thus would be difficult to do in the build step - but perhaps I'm missing something?

My ultimate goal is to do codegen on client libraries (Javascript, Python, Rust) that will be calling the API, where the Rust Rocket code will be the source of truth. The Javascript case in particular is a bit circular; the JS FE code should be dependent on the Rust BE source of truth, but the BE will ultimately need to be linked to the FE code (so that it can be served). The FE isn't in the binary, so it's doable even if I can't get the spec as part of the build step, but I am trying to determine the minimum dependency path for both dev and production cases.

[ralpha]

@nathanielford I'm not quite sure what you mean.
For the build.rs I'm not sure how this works. But I thinks you should be able to get the datastructure or openapi.json file in the build script with the code above. Okapi generates the datastructured during compilation. It uses derive macros and other macros for this. (it basically generates code during compilation and then compiles that)

In regards to the frontend/backend a very common thing is to create a backend in Rust (in this case) with Rocket and expose a (REST) API. This api is then used in JS to populate webpages with data. This means separations of backend and frontend.
Do you want to dynamically generate JS using the Rust build.rs script or what are you asking?

I use the okapi to generate the docs for the API so they can be viewed by the frontend developers and okapi helps with keeping them up to date at all times. (here you can find documentation of my api: https://docs.dfstoryteller.com/rapidoc/ )
The frontend is totally independent of the backend code (and is written in JS mostly).
Here you can find a very simple example of how JS code could look like: https://gitlab.com/df_storyteller/df-storyteller-sketches/-/blob/master/Simple%20list/index.html

I hope this answers your question. If not, could you explain it a bit more what you are looking for?

[nathanielford]

Mostly I'm looking to get an artifact that openapi codegen libraries can use, while minimizing the dependency tree. The goal of the codegen is to have functions created in the client-side applications that are already fully in line with api spec. This makes a class of errors apparent during development rather than a later testing stage.

In this case, the openapi.json file that gets generated is the artifact I'm looking for - it's just not available unless you're running the web application (per your original comment). So, if I'm running yarn build or yarn build-with-codegen (or whatever script I'm using to properly prepare my js files), and that requires the openapi.json file, I need to currently build and start the rocket server, make a fake call to it and save it out. That's a lot of lifting for a file that ought to be generate-able based on source alone. Thus, I was looking at build.rs (which runs by default when you build) to see if I can short circuit doing a full compilation of the rocket server artifact. The Little Book of Rust Macros at least seems to suggest the rust compilation is structured in such a way that this is possible, but I will have to learn a lot more about macros to convince myself of that - hence reaching out.

All that said, in a strictly 'is this doable' sense I think you've answered my question: yes. It also seems like the axios library forgoes explicit codegen for a client object that has it all wrapped inside, which is something I did not know yesterday. In that sense, doing this in the build step may be unneeded, at least for javascript, and so that is the road I'm presently taking. I appreciate your time!

[ralpha]

TL;DR: Yes it is possible, just call the function inside your build.rs to get the structure (note that it has to be library crate in that case, not a binary crate). You however need to modify some crates to do this. As it is not in the main repo at the moment.

With the code in my first post you can do something like this:

let openapi = api::get_openapi(); // see code above
api::write_json_file(output, &openapi).ok();

And the write function (if need be):

/// Write A Json object to a file
pub fn write_json_file<P: AsRef<std::path::Path>, C: Serialize>(
    filename: P,
    object: &C,
) -> Result<(), Error> {
    let mut file = File::create(filename)?;
    let json_string = serde_json::to_string_pretty(object)?;
    file.write_all(json_string.as_bytes())?;
    Ok(())
}

You can most likely just call this in the build.rs
you can use the file or just the data structures.

To not duplicate the code you have to create a new function something like this:

fn get_spec_and_routes() -> (OpenApi, Vec<Route>) {
    let (spec, routes) = routes_and_spec_with_openapi![
        //... all routes here...
    ];
    (spec, routes)
}

I do this here: https://gitlab.com/df_storyteller/df-storyteller/-/blob/0c9e609f4c2e9723c799a085020425c9be71fa52/df_st_api/src/api/mod.rs#L42

I changed rocket_okapi-codegen to do this: https://gitlab.com/df_storyteller/df-storyteller/-/blob/0c9e609f4c2e9723c799a085020425c9be71fa52/df_rocket_okapi_codegen/src/lib.rs

This might be added into the repo itself at some point. But is not there right now.
The code is MIT licensed in the https://gitlab.com/df_storyteller/df-storyteller/-/tree/master/df_rocket_okapi_codegen crate. so feel free to use it. It has some additional changes to, so take a look before using it.

It is not strait forward, but using my code as an example you might be able to figure it out. (just follow the function calls)
If you have questions, let me know!

(To get started you might be able to use: https://crates.io/crates/df_rocket_okapi_codegen , But this is custom and will be deprecated at some point when changes are in rocket_okapi_codegen, so for testing this is okay, but otherwise fork it or create your own version. )

[ralpha]

Getting the OpenApi object is now very easy in okapi/rocket-okapi without needing to jump to hoops.

You can use the openapi_get_routes_spec or openapi_get_spec macro depending on your needs.
See this example for more info: https://github.com/GREsau/okapi/tree/master/examples/custom_schema