apistos

Introduction to Apistos

Apistos is an OpenAPI documentation tool designed to simplify the generation of API documentation for developers using actix-web. OpenAPI Specification (OAS) 3.0 models are supported by Apistos, and it serves as a companion tool similar to paperclip—a well-known documentation generator. Apistos stands out by offering a seamless integration experience for actix-web users, enhancing development efficiency and accuracy.

Components of Apistos

Apistos is composed of several crates, each serving a specific function:

• apistos: This is the primary component that acts as an actix-web wrapper to generate the OpenAPI v3.0.3 documentation file. It ensures that documentation creation is smooth and seamless.

• apistos-core: This crate contains a set of common models and traits applicable to OpenAPI v3.0.3. It standardizes the way OpenAPI elements are defined and utilized.

• apistos-gen: Provides macro utilities allowing developers to generate OpenAPI v3.0.3 documentation directly from Rust models. This crate automates many of the manual processes involved in documentation creation, reducing developer workload.

• apistos-models: This crate includes models following the OpenAPI v3.0.3 specification. It integrates Schema definitions based on the schemars library, ensuring models are comprehensive and compliant.

• apistos-plugins: Offers traits and utilities that help in extending the capabilities of Apistos, enabling users to customize and enhance functionality as per specific project needs.

• apistos-rapidoc: Bridges between Apistos and RapiDoc for users of actix. It allows users to view and interact with documentation through the RapiDoc interface.

• apistos-redoc: This component connects Apistos with Redoc, another popular interface for viewing API documentation.

• apistos-scalar: Provides a bridge between Apistos and Scalar, aiding developers in integrating with Scalar platforms.

• apistos-shuttle: Enables developers to run an actix-web server documented with Apistos on Shuttle, enhancing deployment flexibility.

• apistos-swagger-ui: Integrates Apistos with Swagger UI, providing a widely recognized interface for developers to engage with API documentation.

The Meaning Behind Apistos

The name "Apistos" is a clever wordplay, merging “API” with “Héphaïstos”—the Greek god of blacksmiths and craftsmen, symbolizing craftsmanship and technology. This reflects its purpose as a tool for API craftsmanship.

How to Get Started with Apistos

Installation

To begin using Apistos with your Rust project, include it in your Cargo.toml:

[dependencies]
# For this example, we rely on a schemars fork for compatibility reasons
schemars = { package = "apistos-schemars", version = "0.8" }
apistos = "0.4"

Usage Example

Apistos integration is straightforward. It wraps around the usual actix-web application types, allowing for easy substitution and minimal learning curve. Here’s a simple example showcasing its usage:

use std::fmt::Display;
use actix_web::{App, HttpServer, ResponseError};
use apistos::actix::CreatedJson;
use apistos::api_operation;
use apistos::web::{post, resource, scope};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug, Clone, JsonSchema)]
pub struct Test {
  pub test: String
}

#[api_operation(
  tag = "pet",
  summary = "Add a new pet to the store",
  description = "Add a new pet to the store",
  error_code = 405
)]
pub async fn test(body: Json<Test>) -> Result<CreatedJson<Test>, Error> {
  Ok(CreatedJson(body.0))
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
  HttpServer::new(|| {
    App::new()
      .service(scope("/test").service(resource("").route(post().to(test))))
  })
  .bind("127.0.0.1:8080")?
  .run()
  .await
}

Feature Flags

Apistos supports several feature flags that enable additional functionalities, such as:

• query: Default feature enabling documentation for actix-web query types.
• actix: Default feature supporting the documentation of core actix types.
• rapidoc, redoc, swagger-ui: Flags that support exposing generated documentation through different interfaces like RapiDoc, Redoc, and Swagger UI.
• extras: Bundles multiple supportive libraries enhancing the documentation of data types like UUIDs, URLs, etc.

Exploring Alternatives

While Apistos aligns closely with actix-web, there are alternative tools for generating API documentation:

1. Paperclip: Known for generating Swagger v2 documentation. It includes a tool to generate Rust code from Swagger documents.
2. Utoipa: Relies on actix web macros for route definition. It has limitations regarding generic struct support.
3. Okapi: Powered by schemars but doesn't integrate with actix.

Apistos' design caters to actix-web users requiring a consistent and comprehensive documentation solution with deep integration.

In Closing

Apistos is developed and maintained by Netwo, a remote-first telecom company based in France. While it meets internal requirements, the project is open to community contributions via pull requests, ensuring continuous improvement and adaptation to user needs. Visit Netwo Career Page to learn more about the company and career opportunities.