Crate clawspec_core

Clawspec Core

Generate OpenAPI specifications from your HTTP client test code.

This crate provides two main ways to generate OpenAPI documentation:

• ApiClient - Direct HTTP client for fine-grained control
• TestClient - Test server integration with automatic lifecycle management

Quick Start

Using ApiClient directly

use clawspec_core::ApiClient;

let mut client = ApiClient::builder()
    .with_host("api.example.com")
    .build()?;

// Make requests - schemas are captured automatically  
let user: User = client
    .get("/users/123")?
    .await?  // ← Direct await using IntoFuture
    .as_json()  // ← Important: Must consume result for OpenAPI generation!
    .await?;

// Generate OpenAPI specification
let spec = client.collected_openapi().await;

Using TestClient with a test server

For a complete working example, see the axum example.

use clawspec_core::test_client::{TestClient, TestServer};
use std::net::TcpListener;

#[tokio::test]
async fn test_api() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = TestClient::start(MyServer).await?;
     
    // Test your API
    let response = client.get("/users")?.await?.as_json::<serde_json::Value>().await?;
     
    // Write OpenAPI spec
    client.write_openapi("api.yml").await?;
    Ok(())
}

Working with Parameters

use clawspec_core::{ApiClient, CallPath, CallQuery, CallHeaders, ParamValue};

// Path parameters
let mut path = CallPath::from("/users/{id}");
path.add_param("id", ParamValue::new(123));

// Query parameters
let query = CallQuery::new()
    .add_param("page", ParamValue::new(1))
    .add_param("limit", ParamValue::new(10));

// Headers
let headers = CallHeaders::new()
    .add_header("Authorization", "Bearer token");

// Direct await with parameters:
let response = client
    .get(path)?
    .with_query(query)
    .with_headers(headers)
    .await?;  // Direct await using IntoFuture

Status Code Validation

By default, requests expect status codes in the range 200-499 (inclusive of 200, exclusive of 500). You can customize this behavior:

use clawspec_core::{ApiClient, expected_status_codes};

// Single codes
client.post("/users")?
    .with_expected_status_codes(expected_status_codes!(201, 202))
     
    .await?;

// Ranges
client.get("/health")?
    .with_expected_status_codes(expected_status_codes!(200-299))
     
    .await?;

Schema Registration

use clawspec_core::{ApiClient, register_schemas};

#[derive(Deserialize, ToSchema)]
struct CreateUser { name: String, email: String }

#[derive(Deserialize, ToSchema)]
struct ErrorResponse { code: String, message: String }

// Register schemas for complete documentation
register_schemas!(client, CreateUser, ErrorResponse);

Error Handling

The library provides two main error types:

• ApiClientError - HTTP client errors (network, parsing, validation)
• TestAppError - Test server lifecycle errors

See Also

• ApiClient - HTTP client with OpenAPI collection
• ApiCall - Request builder with parameter support
• test_client - Test server integration module
• ExpectedStatusCodes - Status code validation

Re-exports

All commonly used types are re-exported from the crate root for convenience.

Modules

test_client

Generic test client framework for async server testing.

Macros

expected_status_codes

Creates an ExpectedStatusCodes instance with the specified status codes and ranges.

register_schemas

Registers multiple schema types with the ApiClient for OpenAPI documentation.

Structs

ApiCall

Builder for configuring HTTP API calls with comprehensive parameter and validation support.

ApiClient

A type-safe HTTP client for API testing and OpenAPI documentation generation.

ApiClientBuilder

Builder for creating ApiClient instances with comprehensive configuration options.

CallBody

Represents the body of an HTTP request with its content type and schema information.

CallHeaders

Represents HTTP headers for an API call.

CallPath

A parameterized HTTP path with type-safe parameter substitution.

CallQuery

A collection of query parameters for HTTP requests with OpenAPI 3.1 support.

CallResult

Represents the result of an API call with response processing capabilities.

ExpectedStatusCodes

Expected status codes for HTTP requests.

ParamValue

A parameter value with its serialization style

RawResult

Represents the raw response data from an HTTP request.

Enums

ApiClientError

Errors that can occur when using the ApiClient.

ParamStyle

Parameter styles supported by OpenAPI 3.1 specification.

RawBody

Represents the body content of a raw HTTP response.

Traits

ParameterValue

A trait alias for types that can be used as parameter values.