---
# Library API Documentation - Manual API Docs Example | Oxidoc (lib/index)

---
title: Library API Documentation - Manual API Docs Example | Oxidoc
description: Example of writing manual API documentation with Oxidoc. Create library reference pages with full control over layout alongside auto-generated OpenAPI docs.
---

# Library API Documentation

This section demonstrates how to write **manual API documentation** using Oxidoc. Unlike the auto-generated [API Reference](/api) which parses an OpenAPI spec, manual API docs give you full control over the content and layout.

<Callout kind="info" title="When to use manual API docs">
Manual API docs are ideal for:
- Libraries and packages (Rust crates, npm packages, Python modules)
- Projects with only a few endpoints that don't need a full OpenAPI spec
- Internal tools where you want richer explanations than a spec provides
- SDK documentation with code examples in multiple languages
</Callout>

## How It Works

This entire `/lib` section lives in a separate `lib/` content directory — independent from the main `docs/` directory. Oxidoc supports multiple content directories, each with its own sidebar and URL path.

Here is the config that powers this section:

<CodeBlock language="toml" filename="oxidoc.toml">
[routing]
header_links = [
  { label = "Docs", href = "/" },
  { label = "Lib", href = "/lib" },
  { label = "API", href = "/api" },
]
navigation = [
  { path = "/", dir = "docs", groups = [...] },
  { path = "/lib", dir = "lib", groups = [
    { group = "Library API", pages = [
      "index",
      "manual-api",
      "library-example",
    ] },
  ] },
  { path = "/api", openapi = "./openapi.yaml" },
]
</CodeBlock>

Key points:

- `dir = "lib"` tells Oxidoc to scan the `lib/` directory for `.rdx` files
- Each content directory gets its own sidebar navigation
- Search works across **all** sections — docs, lib, and API pages are all searchable together
- You can add as many content directories as you need

<CardGrid>
<Card title="Manual API Guide" icon="📝" href="/lib/manual-api">
Learn how to write API documentation manually in RDX.
</Card>
<Card title="Library Example" icon="📦" href="/lib/library-example">
A complete example documenting a library's public API.
</Card>
</CardGrid>


---
# Writing Manual API Docs - Hand-Crafted References (lib/manual-api)

---
title: Writing Manual API Docs - Hand-Crafted References 
description: Learn how to write manual API documentation in Oxidoc using RDX components. Create structured reference pages with code examples and parameter tables.
---

# Writing Manual API Docs

When your project doesn't have an OpenAPI spec — or when you want more control over how your API is presented — you can write API documentation manually using RDX components. This page shows the patterns you can use.

## Documenting an Endpoint

Use a combination of headings, code blocks, tables, and callouts to describe each endpoint clearly. Here is a complete example of a single endpoint documented manually:

---

### `POST /api/users` <Badge variant="tip">Stable</Badge>

Create a new user account.

**Parameters**

| Parameter | Type | Required | Description |
|:----------|:-----|:---------|:------------| 
| `name` | string | Yes | The user's display name |
| `email` | string | Yes | Email address |
| `role` | string | No | Role assignment (default: `"member"`) |

**Request body**

```json
{
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin"
}
```

**Response (201 Created)**

```json
{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin",
  "created_at": "2025-01-15T10:30:00Z"
}
```

**Code examples**

<Tabs>
<Tab title="curl">
```bash
curl -X POST https://api.example.com/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'
```
</Tab>
<Tab title="JavaScript">
```javascript
const response = await fetch("https://api.example.com/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Alice", email: "alice@example.com" }),
});
```
</Tab>
<Tab title="Python">
```python
import requests

response = requests.post(
    "https://api.example.com/api/users",
    json={"name": "Alice", "email": "alice@example.com"},
)
```
</Tab>
</Tabs>

<Callout kind="info" title="Authentication">
This endpoint requires a valid API key in the `Authorization` header.
</Callout>

---

## Patterns Used Above

The example above uses these RDX features — all of which you can see in action on this page:

- **Headings** with inline code for the method and path
- **Badge** component to show endpoint status (Stable, Beta, Deprecated)
- **Tables** for parameters
- **Fenced code blocks** for request/response JSON
- **Tabs** for multi-language code examples
- **Callout** for authentication notes

## Organizing API Docs

For larger APIs, use sidebar groups to organize endpoints by resource:

<CodeBlock language="toml" filename="oxidoc.toml">
{ path = "/lib", dir = "lib", groups = [
  { group = "Overview", pages = ["index"] },
  { group = "Users", pages = ["users/create", "users/list", "users/get"] },
  { group = "Projects", pages = ["projects/create", "projects/list"] },
] }
</CodeBlock>

Each page in `lib/users/create.rdx` documents one endpoint or a closely related set of endpoints.

## Tips

<Callout kind="tip" title="Badges for status">
Use Badge components to mark endpoint status:

<Badge variant="tip">Stable</Badge> <Badge variant="warning">Beta</Badge> <Badge variant="deprecated">Deprecated</Badge>
</Callout>

<Callout kind="tip" title="Callouts for auth">
Use Callout blocks to highlight authentication requirements, rate limits, or other important notes that apply to specific endpoints.
</Callout>


---
# Library API Example - Sample Reference Page (lib/library-example)

---
title: Library API Example - Sample Reference Page 
description: A complete example of documenting a library's public API with Oxidoc. Demonstrates function signatures, parameter tables, and interactive code samples.
---

# Library API Example

This page shows a complete example of documenting a library's public API using manual RDX documentation. We'll document a fictional `oxidoc-store` key-value storage library.

---

## oxidoc-store

A fast, typed key-value store for Rust applications.

<CodeBlock language="bash">
cargo add oxidoc-store
</CodeBlock>

---

## `Store::new`

Create a new in-memory store.

<CodeBlock language="rust" filename="lib.rs">
use oxidoc_store::Store;

let store = Store::new();
</CodeBlock>

| Parameter | Type | Description |
|:----------|:-----|:------------|
| _(none)_ | — | Creates an empty store with default settings |

**Returns:** `Store` — A new store instance.

---

## `Store::with_capacity`

Create a store with pre-allocated capacity.

<CodeBlock language="rust" filename="lib.rs">
let store = Store::with_capacity(1000);
</CodeBlock>

| Parameter | Type | Description |
|:----------|:-----|:------------|
| `capacity` | `usize` | Number of entries to pre-allocate |

**Returns:** `Store` — A new store with the given capacity.

<Callout kind="tip" title="Performance">
Use `with_capacity` when you know the approximate number of entries to avoid reallocations.
</Callout>

---

## `Store::set` <Badge variant="tip">Stable</Badge>

Insert or update a key-value pair.

<CodeBlock language="rust" filename="lib.rs">
store.set("user:1", User { name: "Alice", age: 30 });
</CodeBlock>

| Parameter | Type | Description |
|:----------|:-----|:------------|
| `key` | `&str` | The key to store under |
| `value` | `impl Serialize` | The value to store (must implement `serde::Serialize`) |

**Returns:** `Option<Value>` — The previous value if the key already existed, or `None`.

---

## `Store::get` <Badge variant="tip">Stable</Badge>

Retrieve a value by key.

<CodeBlock language="rust" filename="lib.rs">
let user: Option<User> = store.get("user:1");
</CodeBlock>

| Parameter | Type | Description |
|:----------|:-----|:------------|
| `key` | `&str` | The key to look up |

**Returns:** `Option<T>` — The value deserialized to type `T`, or `None` if not found.

---

## `Store::delete`

Remove a key-value pair.

<CodeBlock language="rust" filename="lib.rs">
let removed: bool = store.delete("user:1");
</CodeBlock>

| Parameter | Type | Description |
|:----------|:-----|:------------|
| `key` | `&str` | The key to remove |

**Returns:** `bool` — `true` if the key existed and was removed.

---

## `Store::list` <Badge variant="warning">Beta</Badge>

List all keys matching a prefix.

<CodeBlock language="rust" filename="lib.rs">
let user_keys: Vec<String> = store.list("user:");
</CodeBlock>

| Parameter | Type | Description |
|:----------|:-----|:------------|
| `prefix` | `&str` | Key prefix to filter by |

**Returns:** `Vec<String>` — All keys starting with the given prefix.

---

## `Store::persist` <Badge variant="new">New</Badge>

Save the store to disk.

<CodeBlock language="rust" filename="lib.rs">
store.persist("./data/store.bin")?;
</CodeBlock>

| Parameter | Type | Description |
|:----------|:-----|:------------|
| `path` | `impl AsRef<Path>` | File path to write to |

**Returns:** `Result<()>` — Error if the file cannot be written.

<Callout kind="warning" title="File locking">
`persist` acquires an exclusive file lock. Do not call from multiple processes simultaneously.
</Callout>

---

## `Store::load`

Load a store from a previously persisted file.

<CodeBlock language="rust" filename="lib.rs">
let store = Store::load("./data/store.bin")?;
</CodeBlock>

| Parameter | Type | Description |
|:----------|:-----|:------------|
| `path` | `impl AsRef<Path>` | File path to read from |

**Returns:** `Result<Store>` — The restored store, or an error if the file is missing or corrupt.

---

## Full Example

<CodeBlock language="rust" filename="main.rs" highlight="5,8,11">
use oxidoc_store::Store;
use serde::{Serialize, Deserialize};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::new();

    // Insert data
    store.set("config:theme", "dark");
    store.set("config:lang", "en");

    // Retrieve
    let theme: Option<String> = store.get("config:theme");
    println!("Theme: {:?}", theme);

    // List by prefix
    let configs = store.list("config:");
    println!("Config keys: {:?}", configs);

    // Persist to disk
    store.persist("./app.store")?;

    Ok(())
}
</CodeBlock>