Crate rocket_autodocu

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 = { version = "0.5.0-rc.1", default-features = false, features = ["json"] }
schemars = "0.8"
autodocu = { version = "0.6.0-alpha-1" }
rocket_autodocu = { version = "0.9.1", features = ["swagger"] }

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 openapi_get_routes!. 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

use rocket::get;
use rocket::serde::json::Json;
use rocket_autodocu::{openapi, openapi_get_routes, JsonSchema};
use rocket_autodocu::swagger_ui::{make_swagger_ui, SwaggerUIConfig};

#[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_autodocu::settings::UrlObject;

    SwaggerUIConfig {
        url: "/my_resource/openapi.json".to_string(),
        ..Default::default()
    }
}

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

This crate exposes a few macros that can be used to generate and serve routes and OpenApi objects.

• mount_endpoints_and_merged_docs!{...}: Mount endpoints and mount merged OpenAPI documentation.
• openapi_get_routes![...]: To generate and add the openapi.json route.
• openapi_get_routes_spec![...]: To generate and return a list of routes and the openapi spec.
• openapi_get_spec![...]: To generate and return the openapi spec.

The last 3 macros have very similar behavior, but differ in what they return. Here is a list of the marcos and what they return:

• openapi_get_routes![...]: Vec<rocket::Route> (adds route for openapi.json)
• openapi_get_routes_spec![...]: (Vec<rocket::Route>, autodocu::openapi3::OpenApi)
• openapi_get_spec![...]: autodocu::openapi3::OpenApi

Re-exports

• pub use autodocu;

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.
• rapidoc
  Contains the functions and structs required to display the RapiDoc UI.
• 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 UI.
• util
  Assorted function that are used throughout the application.

Macros

• hash_map
  Macro to crate a HashMap with a number of key-value pairs in it.
• mount_endpoints_and_merged_docs
  Mount endpoints and mount merged OpenAPI documentation.
• openapi_get_routes
  A replacement macro for rocket::routes. This also takes a optional settings object.
• openapi_get_routes_spec
  A replacement macro for rocket::routes. This parses the routes and provides a tuple with 2 parts (Vec<rocket::Route>, OpenApi):
• openapi_get_spec
  Generate OpenApi spec only, does not generate routes. This can be used in cases where you are only interested in the openAPI spec, but not in the routes. A use case could be inside of build.rs scripts or where you want to alter OpenAPI object at runtime.
• openapi_routes
  Generate and return a closure that can be used to generate the routes.
• openapi_spec
  Generate and return a closure that can be used to generate the OpenAPI specification.

Structs

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

Traits

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

Functions

• get_openapi_route
  Convert OpenApi object to routable endpoint.

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_autodocu::request, and that the return type implements OpenApiResponder.

Derive Macros

• JsonSchema
• OpenApiFromRequest
  Derive marco for the OpenApiFromRequest trait.