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>