Uselink api docs

API Docs → Uselink

Scan a codebase for API endpoints, generate clean API documentation as HTML, and publish to uselink.

When to Use

• "Generate API docs and share them"
• "Document our endpoints for the frontend team"
• "Share the API contract with the mobile dev"
• "What endpoints do we have? Publish a reference."

Prerequisites

which uselink || echo "MISSING"
test -f ~/.uselink/config.json && echo "OK" || echo "NO_CONFIG"

Workflow

1. Detect framework and find endpoints

Micronaut/Kotlin:

grep -rn "@Controller\|@Get\|@Post\|@Put\|@Delete" \
  --include="*.kt" -l | grep -v build | grep -v test

Express/Node:

grep -rn "router\.\(get\|post\|put\|delete\)\|app\.\(get\|post\|put\|delete\)" \
  --include="*.ts" --include="*.js" -l | grep -v node_modules | grep -v test

FastAPI/Python:

grep -rn "@app\.\(get\|post\|put\|delete\)\|@router\.\(get\|post\|put\|delete\)" \
  --include="*.py" -l | grep -v __pycache__ | grep -v test

Spring/Java:

grep -rn "@RestController\|@GetMapping\|@PostMapping\|@RequestMapping" \
  --include="*.java" --include="*.kt" -l | grep -v build | grep -v test

2. Read each controller

For each controller file:

• Extract the base path (e.g., @Controller("/api/v1/documents"))
• Extract each endpoint: method, path, query params, body type, return type
• Extract auth requirements (e.g., @Secured, middleware)
• Read the request/response DTOs to get field names and types

3. Group endpoints

Group by resource/domain:

• /api/v1/documents/* → Documents
• /api/v1/auth/* → Authentication
• /api/v1/comments/* → Comments

4. Generate HTML

Write to /tmp/uselink-api-docs-<project>-<timestamp>.html.

<!-- API header -->
<div class="card">
  <h3>{{PROJECT}} API Reference</h3>
  <p class="muted">{{ENDPOINT_COUNT}} endpoints · Generated {{DATE}}</p>
  <p>Base URL: <code>{{BASE_URL}}</code></p>
</div>

<!-- Table of contents -->
<h2>Endpoints</h2>
<table>
  <thead><tr><th>Method</th><th>Path</th><th>Description</th><th>Auth</th></tr></thead>
  <tbody>
    <tr>
      <td><span class="tag tag-done">POST</span></td>
      <td><code>{{PATH}}</code></td>
      <td>{{SHORT_DESC}}</td>
      <td>{{AUTH_REQUIREMENT}}</td>
    </tr>
  </tbody>
</table>

<!-- Per-resource sections -->
<h2>{{RESOURCE_NAME}}</h2>

<!-- Per-endpoint detail -->
<h3><span class="tag tag-done">POST</span> <code>{{PATH}}</code></h3>
<div class="card">
  <p>{{DESCRIPTION}}</p>

  <h4>Query Parameters</h4>
  <table>
    <thead><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
    <tbody>
      <tr><td><code>{{PARAM}}</code></td><td>{{TYPE}}</td><td>{{REQ}}</td><td>{{DESC}}</td></tr>
    </tbody>
  </table>

  <h4>Request Body</h4>
  <pre><code>{{REQUEST_JSON_EXAMPLE}}</code></pre>

  <h4>Response</h4>
  <pre><code>{{RESPONSE_JSON_EXAMPLE}}</code></pre>
</div>

Use color-coded method tags:

• GET → green (tag-done)
• POST → blue (tag-nit)
• DELETE → red (tag-bug)

5. Publish

uselink publish /tmp/uselink-api-docs-<project>-<timestamp>.html \
  --title "API Reference -- <project> -- <date>" \
  --format html

Return the URL to the user.

Gotchas

• NEVER set background or color on body, table, th, td, code, or pre. uselink's viewer injects theme-adaptive CSS that handles light/dark mode automatically. Any hardcoded color in published HTML overrides the viewer's theme and forces a white background in dark mode. Only style layout (padding, margins, borders, border-radius, font-size, grid). Use opacity for muted text instead of color: #888.
• Generate example JSON, don't guess. Read the actual DTO/model classes to get field names, types, and defaults. Don't invent example values that don't match the schema.
• Use snake_case in JSON examples if that's the wire format. Check the project's serialization config (Jackson SNAKE_CASE, etc.) and match the actual API output.
• Skip internal/admin endpoints unless asked. If the docs are for external consumers, filter out admin-only routes. Ask the user if unclear.
• Auth info matters. Always show whether an endpoint requires authentication and what role/scope is needed. Stakeholders need this to understand access patterns.
• HTML-escape all code examples. JSON with angle brackets or ampersands in string values will corrupt the HTML.
• Large APIs need a TOC. If there are 20+ endpoints, the table of contents at the top is critical for navigation.