Skip to content
OpenAPI (AKA Swagger) document generation for Rust projects
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.
okapi v0.4.0 Mar 26, 2020
Cargo.toml Move rocket-okapi binary to examples Aug 18, 2019
LICENSE Initial commit Aug 8, 2019 Add basic usage and list of TODOs to readme Sep 15, 2019


OpenAPI (AKA Swagger) document generation for Rust projects

Work in progress!

Basic Usage

#![feature(proc_macro_hygiene, decl_macro)]

extern crate rocket;
extern crate rocket_okapi;

use rocket_contrib::json::Json;
use rocket_okapi::swagger_ui::make_swagger_ui;
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;

// Derive JsonSchema for and request/response models
#[derive(Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
struct User {
    user_id: u64,
    username: String,
    email: Option<String>,

// Add #[openapi] attribute to your routes
fn get_user(id: u64) -> Option<Json<User>> {
    Some(Json(User {
        user_id: id,
        username: "bob".to_owned(),
        email: None,

// You can skip routes that you don't want to include in the openapi doc
fn hidden() -> Json<&'static str> {
    Json("Hidden from swagger!")

pub fn make_rocket() -> rocket::Rocket {
        // routes_with_openapi![...] will host the openapi document at openapi.json
            routes_with_openapi![get_user, hidden],
        // You can optionally host swagger-ui too
            make_swagger_ui(&SwaggerUIConfig {
                url: Some("../openapi.json".to_owned()),
                urls: None,


  • Tests
  • Documentation
  • Benchmark/optimise memory usage and allocations
  • Implement OpenApiFrom___/OpenApiResponder for more rocket/rocket-contrib types
  • Allow customizing openapi generation settings, e.g.
    • custom json schema generation settings
    • change path the document is hosted at
You can’t perform that action at this time.