v3.1.0APIs & Backend

API Documentation Generator

Generiert automatisch OpenAPI/Swagger-Dokumentation aus Velisch-Code mit HTTP-Decorators.

Installation

cd tools/api-doc-generator
cargo build --release

Verwendung

OpenAPI JSON generieren

velin-api-doc generate -i main.velin -o openapi.json

OpenAPI YAML generieren

velin-api-doc generate -i main.velin -o openapi.yaml --format yaml

Markdown Dokumentation

velin-api-doc generate -i main.velin -o api.md --format markdown

Mit Custom Titel und Version

velin-api-doc generate -i api.velin -o openapi.json \
  --title "My Awesome API" \
  --version "2.0.0"

Unterstützte Features

HTTP Endpoints

Alle Funktionen mit HTTP-Decorators werden automatisch erkannt.

@GET("/api/users/:id")
fn getUser(id: string): User {
    return db.find(User, id);
}

@POST("/api/users")
fn createUser(name: string, email: string): User {
    return db.save(User { name, email });
}
Schemas

Structs und Enums werden als OpenAPI Schemas generiert.

struct User {
    id: string,
    name: string,
    email: string,
}

enum Status {
    Active,
    Inactive,
}

Security Schemes

Security-Decorators werden automatisch als Security Schemes generiert:

@GET("/api/admin/users")
@Auth
fn getAdminUsers(): List<User> {
    return db.findAll(User);
}

Wird zu:

{
  "security": [{"bearerAuth": []}],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}

Vollständiges Beispiel

Velisch Code

struct User {
    id: string,
    name: string,
    email: string,
}

@GET("/api/users/:id")
@Auth
fn getUser(id: string): User {
    return db.find(User, id);
}

Generierte OpenAPI Spec

{
  "openapi": "3.0.0",
  "info": {
    "title": "Velisch API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/users/{id}": {
      "get": {
        "operationId": "get_user",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {"type": "string"}
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/User"}
              }
            }
          }
        },
        "security": [{"bearerAuth": []}]
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "email": {"type": "string"}
        },
        "required": ["id", "name", "email"]
      }
    }
  }
}

Integration

Swagger UI

# OpenAPI Spec generieren
velin-api-doc generate -i main.velin -o openapi.json

# Mit Docker Swagger UI starten
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/openapi.json \
  -v $(pwd):/openapi \
  swaggerapi/swagger-ui

CI/CD Integration

.github/workflows/api-docs.ymlyaml
- name: Generate API Documentation
  run: |
    cd tools/api-doc-generator
    cargo build --release
    ./target/release/velin-api-doc generate \
      -i ../examples/api.velin \
      -o api-docs/openapi.json \
      --title "Velisch API" \
      --version "1.0.0"

Best Practices

Regelmäßig aktualisieren

Generiere Docs bei jedem Release

Versionierung

Verwende --version für API-Versionierung

Beschreibende Titel

Verwende aussagekräftige --title Werte

CI/CD Integration

Integriere in deine Deployment-Pipeline

OpenAPIRate Limiting