Saltar al contenido principal

Swagger Documentation

En el mundo de las APIs modernas, donde la documentación precisa y actualizada es crucial para el éxito de cualquier plataforma, Swagger emerge como el estándar de facto para documentar interfaces REST. En KodeChain, este sistema no solo documenta endpoints; crea una experiencia interactiva que permite a desarrolladores explorar, probar y entender la API sin escribir una sola línea de código.

La Arquitectura de Swagger​

Generación Automática desde Código​

//go:generate swag init -g main.go -o docs/

Un simple comando genera toda la documentación desde comentarios especiales en el código Go.

Estructura de Archivos Generados​

docs/
├── docs.go      # Código Go generado con especificaciones
├── swagger.json # Especificación OpenAPI 2.0 en JSON
└── swagger.yaml # Especificación OpenAPI 2.0 en YAML

Tres formatos diferentes para diferentes necesidades y herramientas.

Comentarios que Generan Documentación​

Estructura de Comentarios​

// getBlockchainStatus godoc
// @Summary Get blockchain status
// @Description Get the status of both DPOS and PBFT chains
// @Tags blockchain
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{}
// @Router /api/blockchain/status [get]
func (s *Server) getBlockchainStatus(c *gin.Context) {
    // Implementación...
}

Cada comentario especial se traduce automáticamente en documentación Swagger.

Tags para Organización​

// @Tags blockchain,transactions,staking,sync

Los tags agrupan endpoints relacionados, creando secciones lógicas en la documentación.

Definiciones de Respuesta​

// @Success 200 {object} endpoints.BlockchainStatusResponse
// @Failure 400 {object} endpoints.ErrorResponse
// @Failure 500 {object} endpoints.ErrorResponse

Especifican exactamente qué estructura de datos retorna cada endpoint.

Especificación OpenAPI 2.0​

Información General​

{
  "swagger": "2.0",
  "info": {
    "description": "API for KodeChain blockchain node",
    "title": "KodeChain Node API",
    "contact": {},
    "version": "1.0"
  },
  "host": "localhost:8080",
  "basePath": "/",
  "schemes": ["http", "https"]
}

La metadata básica que describe la API completa.

Definiciones de Tipos​

"definitions": {
  "endpoints.CreateTransactionRequest": {
    "type": "object",
    "properties": {
      "amount": {
        "type": "integer"
      },
      "data": {
        "type": "string"
      },
      "from": {
        "type": "string"
      },
      "signature": {
        "type": "string"
      },
      "to": {
        "type": "string"
      },
      "type": {
        "description": "\"transfer\", \"stake\", \"unstake\"",
        "type": "string"
      }
    },
    "type": "object"
  }
}

Cada struct Go se convierte automáticamente en una definición de tipo OpenAPI.

Paths y Operaciones​

"/api/transaction/create": {
  "post": {
    "description": "Create a new transaction and add it to the mempool",
    "consumes": ["application/json"],
    "produces": ["application/json"],
    "tags": ["transactions"],
    "summary": "Create a new transaction",
    "parameters": [
      {
        "description": "Transaction creation request",
        "name": "request",
        "in": "body",
        "required": true,
        "schema": {
          "$ref": "#/definitions/endpoints.CreateTransactionRequest"
        }
      }
    ],
    "responses": {
      "201": {
        "description": "Created",
        "schema": {
          "$ref": "#/definitions/endpoints.CreateTransactionResponse"
        }
      }
    }
  }
}

Cada endpoint se describe completamente: método HTTP, parámetros, respuestas, tipos de contenido.

Interfaz Swagger UI​

Explorador Interactivo​

<!DOCTYPE html>
<html>
<head>
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3.25.0/swagger-ui.css" />
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist@3.25.0/swagger-ui-bundle.js"></script>
    <script>
        const ui = SwaggerUIBundle({
            url: '/swagger.json',
            dom_id: '#swagger-ui',
            presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIBundle.SwaggerUIStandalonePreset
            ]
        });
    </script>
</body>
</html>

La interfaz web que permite explorar la API interactivamente.

Funcionalidades Interactivas​

  • Try it out: Ejecutar llamadas API directamente desde el navegador
  • Authentication: Soporte para diferentes métodos de autenticación
  • Request/Response Examples: Ejemplos reales de uso
  • Schema Validation: Validación automática de parámetros

Headers Especiales​

X-Consensus-Type​

parameters:
  - name: X-Consensus-Type
    in: header
    description: Consensus type (DPOS or PBFT)
    required: true
    type: string
    enum: [DPOS, PBFT]

Header crítico que especifica qué cadena debe procesar la solicitud.

Content-Type y Accept​

consumes:
  - application/json
produces:
  - application/json

Especifica los formatos de datos soportados.

Manejo de Errores en Documentación​

Códigos de Estado​

responses:
  "200":
    description: "OK"
  "400":
    description: "Bad Request"
    schema:
      $ref: "#/definitions/endpoints.ErrorResponse"
  "401":
    description: "Unauthorized"
  "403":
    description: "Forbidden"
  "404":
    description: "Not Found"
  "500":
    description: "Internal Server Error"

Cada código de estado está documentado con su significado y estructura de respuesta.

Estructuras de Error​

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "integer"
    },
    "details": {
      "type": "string"
    }
  }
}

Formato consistente para todas las respuestas de error.

Versionado de API​

Versiones en Paths​

basePath: /v1

Soporte para versionado de API a través de paths.

Versiones en Headers​

parameters:
  - name: X-API-Version
    in: header
    type: string
    default: "1.0"

Headers opcionales para especificar versión deseada.

Seguridad en Documentación​

Autenticación​

securityDefinitions:
  BearerAuth:
    type: apiKey
    name: Authorization
    in: header
  ApiKeyAuth:
    type: apiKey
    name: X-API-Key
    in: header

Definición de métodos de autenticación soportados.

Rate Limiting​

responses:
  "429":
    description: "Too Many Requests"
    headers:
      X-RateLimit-Limit:
        type: integer
        description: Request limit
      X-RateLimit-Remaining:
        type: integer
        description: Remaining requests
      X-RateLimit-Reset:
        type: string
        description: Reset time

Documentación de límites de rate limiting.

Testing Automatizado​

Validación de Esquemas​

// Validar que la respuesta cumple con el esquema
const Ajv = require('ajv');
const ajv = new Ajv();

const validate = ajv.compile(schema);
const valid = validate(responseData);

if (!valid) {
    console.error('Response validation failed:', validate.errors);
}

Validación automática de que las respuestas cumplen con los esquemas documentados.

Tests de Contrato​

func TestAPIContract(t *testing.T) {
    // Cargar especificación Swagger
    spec := loadSwaggerSpec("docs/swagger.json")
    
    // Probar cada endpoint
    for path, operations := range spec.Paths {
        for method, operation := range operations {
            t.Run(fmt.Sprintf("%s_%s", method, path), func(t *testing.T) {
                // Ejecutar request
                response := makeRequest(method, path)
                
                // Validar contra esquema
                validateResponse(response, operation.Responses)
            })
        }
    }
}

Tests que aseguran que la implementación cumple con la documentación.

Integración con Herramientas​

Generación de Clientes​

# Generar cliente TypeScript
swagger-codegen generate -i swagger.json -l typescript-fetch -o client-ts

# Generar cliente Go
swagger-codegen generate -i swagger.json -l go -o client-go

# Generar cliente Python
swagger-codegen generate -i swagger.json -l python -o client-py

Generación automática de bibliotecas cliente en múltiples lenguajes.

Testing con Postman/Newman​

{
  "info": {
    "name": "KodeChain API Tests",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Create Transaction",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\"from\":\"0x1000...\",\"to\":\"0x1000...\",\"amount\":1000000000000000000}"
        },
        "url": {
          "raw": "{{baseUrl}}/api/transaction/create",
          "host": ["{{baseUrl}}"],
          "path": ["api", "transaction", "create"]
        }
      }
    }
  ]
}

Colecciones de Postman generadas automáticamente desde Swagger.

Mantenimiento y Evolución​

Actualización Automática​

# En el pipeline CI/CD
swag init -g main.go -o docs/
git add docs/
git commit -m "Update API documentation"

La documentación se mantiene actualizada automáticamente con cada cambio de código.

Versionado Semántico​

info:
  version: "2.1.0"
  title: "KodeChain Node API"
  description: |
    API for KodeChain blockchain node
    
    ## Changelog
    ### 2.1.0
    - Added new staking endpoints
    - Enhanced error responses
    
    ### 2.0.0
    - Breaking change: New consensus types
    - Added PBFT support

Historial de cambios documentado junto con la especificación.

El Rol en el Desarrollo​

Documentación Viva​

La documentación Swagger no es un documento estático; es una representación viva del código que:

  • Se actualiza automáticamente: Con cada cambio en el código
  • Es testable: Los ejemplos se pueden ejecutar directamente
  • Es explorable: Los desarrolladores pueden experimentar sin riesgo
  • Es generativa: Crea clientes y tests automáticamente

Puente entre Equipos​

// Para el backend developer
func createTransaction(c *gin.Context) {
    // Implementación técnica
}

// Para el frontend developer
// POST /api/transaction/create
// Body: {from, to, amount}
// Response: {success, transaction_hash}

La documentación Swagger traduce código técnico en contratos comprensibles.

Calidad y Consistencia​

# Esquemas estrictos aseguran consistencia
definitions:
  Transaction:
    type: object
    required: [from, to, amount]
    properties:
      from: {type: string, pattern: '^0x[a-fA-F0-9]{40}$'}
      to: {type: string, pattern: '^0x[a-fA-F0-9]{40}$'}
      amount: {type: integer, minimum: 0}

Validaciones estrictas que mejoran la calidad de la API.

El Arte de la Documentación​

Cada comentario @Summary, cada @Parameter, cada @Response representa un puente entre la complejidad técnica y la usabilidad práctica. La documentación Swagger de KodeChain no solo describe una API; crea una experiencia donde desarrolladores pueden entender, probar y confiar en cada endpoint.

Desde el primer swag init hasta la interfaz interactiva final, Swagger transforma el código en conocimiento accesible, permitiendo que equipos construyan sobre KodeChain con confianza y precisión.