openapi_ui/lib.rs
1//! # openapi-ui
2//!
3//](https://github.com/kimolalekan/openapi-ui/actions)
4//! [](https://crates.io/crates/openapi-ui)
5//! [](https://docs.rs/openapi-ui)
6//! [](https://opensource.org/licenses/MIT)
7//!
8//! `openapi-ui` is a library for generating custom documentation UIs from OpenAPI specifications.
9//!
10//! It takes an OpenAPI JSON string and produces a self-contained HTML file with a responsive UI.
11//!
12//! **[🌐 Live Demo](https://kimolalekan.github.io/openapi-ui)**
13//!
14//! ## Web Framework Examples
15//!
16//! - [Axum](https://github.com/kimolalekan/openapi-ui/blob/main/examples/axum.rs)
17//! - [Actix-web](https://github.com/kimolalekan/openapi-ui/blob/main/examples/actix.rs)
18//! - [Rocket](https://github.com/kimolalekan/openapi-ui/blob/main/examples/rocket.rs)
19//! - [Warp](https://github.com/kimolalekan/openapi-ui/blob/main/examples/warp.rs)
20//! - [Poem](https://github.com/kimolalekan/openapi-ui/blob/main/examples/poem.rs)
21//! - [Salvo](https://github.com/kimolalekan/openapi-ui/blob/main/examples/salvo.rs)
22//!
23//! ## Generating OpenAPI JSON with utoipa
24//!
25//! The OpenAPI JSON can be generated using [utoipa](https://crates.io/crates/utoipa):
26//!
27//! ```rust,ignore
28//! use utoipa::OpenApi;
29//! use openapi_ui::{generate_docs, ThemeMode};
30//!
31//! #[derive(OpenApi)]
32//! #[openapi(paths(get_users), components(schemas(User)))]
33//! struct ApiDoc;
34//!
35//! let openapi_json = ApiDoc::openapi().to_pretty_json().unwrap();
36//! let html = generate_docs(&openapi_json, ThemeMode::System, None, None).unwrap();
37//! ```
38//!
39//! ## Usage
40//!
41//! ```rust
42//! use openapi_ui::{generate_docs, ThemeMode};
43//!
44//! fn main() -> Result<(), Box<dyn std::error::Error>> {
45//! // Use the sample Petstore API spec (or your own OpenAPI JSON)
46//! let openapi_json = include_str!("sample_data.json");
47//!
48//! // Generate HTML with system theme and default favicon
49//! let html = generate_docs(openapi_json, ThemeMode::System, None, None)?;
50//!
51//! std::fs::write("docs.html", html)?;
52//! Ok(())
53//! }
54//! ```
55//!
56//! For more control, use the [`UIBuilder`]:
57//!
58//! ```rust
59//! use openapi_ui::{UIBuilder, OpenAPISpec};
60//! use std::fs;
61//!
62//! # fn run() -> Result<(), Box<dyn std::error::Error>> {
63//! // Load your OpenAPI spec from file
64//! let spec_json = fs::read_to_string("openapi.json")?;
65//! let spec: OpenAPISpec = serde_json::from_str(&spec_json)?;
66//!
67//! let html = UIBuilder::new(spec)
68//! .theme("dark")
69//! .base_url("https://api.example.com")
70//! .build();
71//!
72//! fs::write("docs.html", html)?;
73//! # Ok(())
74//! # }
75//! ```
76
77pub mod error;
78pub mod openapi;
79pub mod template;
80pub mod theme;
81pub mod ui;
82
83pub use error::{Result, UIError};
84pub use openapi::{HttpScheme, OpenAPISpec, SchemaType};
85pub use theme::{get_complete_theme_css, get_theme_css, ThemeMode};
86pub use ui::{generate_base_ui, generate_docs, generate_ui, UIBuilder, UIConfig};