OpenAPI Schemas & SDKs
Relevant source files
The following files were used as context for generating this wiki page:
Warpgate utilizes a contract-first approach for its internal and external communications by leveraging OpenAPI specifications. Both the Admin API and the Gateway (User) API are defined using the OpenAPI 3.0.0 standard, which allows for the automated generation of client SDKs and interactive documentation (Swagger UI). This ensures that the Rust backend and the Svelte-based frontend remain synchronized regarding data structures and endpoint signatures.
The project uses poem-openapi in the Rust backend to generate these schemas directly from code, and the openapi-generator-cli on the frontend to create TypeScript fetch-based clients.
Sources: README.md:124-126, warpgate-web/package.json:11-16
Architecture and Generation Flow
The generation of OpenAPI components is integrated into the build process. The backend Rust crates define endpoints using procedural macros, which are then compiled into a utility that outputs a JSON schema. The frontend consumes these JSON files to generate a TypeScript SDK.
The Generation Pipeline
This diagram illustrates how the Rust backend serves as the single source of truth for the API contract.
Sources: warpgate-web/package.json:11-17, warpgate-admin/src/main.rs:7-14
Backend Schema Generation
In the warpgate-admin crate, the main.rs file is specifically designed to output the OpenAPI specification. It uses a Regex to clean up generic types (like PaginatedResponse<T>) into a format more compatible with generator tools (e.g., PaginatedT).
pub fn main() {
let api_service =
OpenApiService::new(api::get(), "Warpgate Web Admin", env!("CARGO_PKG_VERSION"))
.server("/@warpgate/admin/api");
let spec = api_service.spec();
let re = Regex::new(r"PaginatedResponse<(?P<name>\w+)>").unwrap();
let spec = re.replace_all(&spec, "Paginated$name");
println!("{spec}");
}
Sources: warpgate-admin/src/main.rs:7-16
API Modules and SDKs
Warpgate maintains two primary API surfaces, each with its own generated SDK located in warpgate-web/src/.
| API Type | Purpose | Local Schema Path | Generated Client Path |
|---|---|---|---|
| Gateway API | User authentication, profile management, and target discovery. | src/gateway/lib/openapi-schema.json | src/gateway/lib/api-client |
| Admin API | Management of users, targets, roles, and system parameters. | src/admin/lib/openapi-schema.json | src/admin/lib/api-client |
Sources: warpgate-web/package.json:11-14, warpgate-web/src/gateway/ProfileApiTokens.svelte:10-33
Build Scripts
The package.json in the web directory defines the commands used to refresh these schemas and clients:
openapi:schema:gateway: Runs thewarpgate-protocol-httpcrate to output the gateway JSON schema.openapi:schema:admin: Runs thewarpgate-admincrate to output the admin JSON schema.openapi:client:gateway: Generates the TypeScript Fetch SDK for the gateway.openapi:client:admin: Generates the TypeScript Fetch SDK for the admin panel.
Sources: warpgate-web/package.json:11-16
Key Data Structures in OpenAPI
The schemas define complex objects that represent the system state. These are mirrored across the Rust poem_openapi::Object structs and the generated TypeScript interfaces.
Example: User and Security Schema
The Gateway API includes a security scheme for API tokens, using the X-Warpgate-Token header.
The data flow for creating a token involves receiving a NewApiToken request and returning a TokenAndSecret response (which includes the cleartext secret only once).
Sources: warpgate-protocol-http/src/api/api_tokens.rs:25-47, warpgate-web/src/gateway/lib/openapi-schema.json:1010-1033
Endpoint Summary (Gateway API)
Commonly used endpoints defined in the OpenAPI schema:
| Path | Method | Operation ID | Description |
|---|---|---|---|
/auth/login | POST | login | Authenticate with username/password. |
/info | GET | get_info | Get server version and current session info. |
/targets | GET | get_targets | List available connection targets. |
/profile/api-tokens | POST | create_api_token | Generate a new programmatic access token. |
Sources: warpgate-web/src/gateway/lib/openapi-schema.json:30-150, warpgate-protocol-http/src/api/info.rs:43-50
Implementation Details
Security Schemes
The API defines an AnySecurityScheme which, in the OpenAPI JSON, is mapped to an apiKey requirement in the header.
"securitySchemes": {
"AnySecurityScheme": {
"type": "apiKey",
"name": "X-Warpgate-Token",
"in": "header"
}
}
Sources: warpgate-web/src/gateway/lib/openapi-schema.json:1037-1043
Rust API Implementation
In the backend, the OpenAPI integration is achieved via the #[OpenApi] attribute on implementation blocks. Methods use attributes like #[oai(path = "...", method = "...")] to define the contract.
#[OpenApi]
impl ListApi {
#[oai(path = "/users", method = "get", operation_id = "get_users")]
async fn api_get_all_users(
&self,
db: Data<&Arc<Mutex<DatabaseConnection>>>,
search: Query<Option<String>>,
_auth: AnySecurityScheme,
) -> Result<GetUsersResponse, WarpgateError> {
// Implementation...
}
}
Sources: warpgate-admin/src/api/users.rs:44-53
Summary
The OpenAPI system in Warpgate provides a robust framework for maintaining API consistency. By generating the schema directly from the Rust backend and then deriving the TypeScript SDKs, the project minimizes manual synchronization errors. This architecture also supports external integrations by providing standardized JSON schemas and a Python SDK for testing purposes.