Crate df_rocket_okapi

This projects serves to enable automatic rendering of openapi.json files, and provides facilities to also serve the documentation alongside your api.

Usage

First, add the following lines to your Cargo.toml

[dependencies]
rocket_okapi = "0.5"
schemars = "0.7"
okapi = { version = "0.5", features = ["derive_json_schema"] }

To add documentation to a set of endpoints, a couple of steps are required. The request and response types of the endpoint must implement JsonSchema. Secondly, the function must be marked with #[openapi]. After that, you can simply replace routes! with routes_with_openapi!. This will append an additional route to the resulting Vec<Route>, which contains the openapi.json file that is required by swagger. Now that we have the json file that we need, we can serve the swagger web interface at another endpoint, and we should be able to load the example in the browser!

Example

#![feature(decl_macro, proc_macro_hygiene)]

use rocket::get;
use rocket_contrib::json::Json;
use rocket_okapi::{openapi, routes_with_openapi, JsonSchema};
use rocket_okapi::swagger_ui::{make_swagger_ui, SwaggerUIConfig};

static APPLICATION_NAME: &'static str = "Test";
static APPLICATION_DESCRIPTION: &'static str = "Test";
static APPLICATION_LICENSE: &'static str = "GPL-3.0-or-later";
static APPLICATION_LICENSE_URL: &'static str = "https://example.com";
static APPLICATION_DOCS_NAME: &'static str = "Rust Docs";
static APPLICATION_DOCS_URL: &'static str = "https://example.com";

#[derive(serde::Serialize, JsonSchema)]
struct Response {
    reply: String,
}

#[openapi]
#[get("/")]
fn my_controller() -> Json<Response> {
    Json(Response {
        reply: "show me the docs!".to_string(),
    })
}

fn get_docs() -> SwaggerUIConfig {
    use rocket_okapi::swagger_ui::UrlObject;

    SwaggerUIConfig {
        url: "/my_resource/openapi.json".to_string(),
        urls: vec![UrlObject::new("My Resource", "/v1/company/openapi.json")],
        ..Default::default()
    }
}

fn main() {
    rocket::ignite()
        .mount("/my_resource", routes_with_openapi![my_controller])
        .mount("/swagger", make_swagger_ui(&get_docs()))
        .launch();
}

Modules

• gen
  Contains the Generator struct, which you can use to manually control the way a struct is represented in the documentation.
• handlers
  Contains several Rocket Handlers, which are used for serving the json files and the swagger interface.
• request
  This module contains several traits that correspond to the Rocket traits pertaining to request guards and responses
• response
  Contains the trait OpenApiResponder, meaning that a response implementing this trait can be documented.
• settings
  Contains then OpenApiSettings struct, which can be used to customize the behavior of a Generator.
• swagger_ui
  Contains the functions and structs required to display the swagger web ui.
• util
  Assorted function that are used throughout the application.

Macros

• routes_and_spec_with_openapi
• routes_with_openapi
  A replacement macro for rocket::routes. The key differences are that this macro will add an additional element to the resulting Vec<rocket::Route>, which serves a static file called openapi.json. This file can then be used to display the routes in the swagger ui.

Structs

• OpenApiError
  The error type returned by rocket_okapi when something fails.
• OperationInfo
  Contains information about an endpoint.

Traits

• JsonSchema
  A type which can be described as a JSON Schema document.

Type Aliases

• Result
  Type alias for Result<T, OpenApiError>.

Attribute Macros

• openapi
  A proc macro to be used in tandem with one of Rocket’s endpoint macros. It requires that all of the arguments of the route implement one of the traits in rocket_okapi::request, and that the return type implements OpenApiResponder.

Derive Macros

• JsonSchema