DMS.Documentation 1.0.1

DMS.Documentation

Paquete NuGet: DMS.Documentation
Autor: Fredy Fuentes
Versión Actual: 1.0.0

📜 Descripción

Biblioteca para generar documentación Swagger/OpenAPI en aplicaciones .NET con ejemplos personalizados, esquemas de seguridad y manejo de errores estandarizados. Ideal para APIs REST que requieren documentación detallada y mantenible.

📝 Características Principales

• Generación automática de ejemplos para solicitudes y respuestas.
• Esquema de seguridad JWT integrado (Bearer Token).
• Manejo de errores estandarizados (400, 401, 500) con ejemplos.
• Personalización de la información básica (título, versión, contacto).
• Soporte para .NET 7.0+ y Swagger/OpenAPI.

📖 Ejemplos de Uso

📖 Configurar Documentación en Program.cs

using DMS.Documentation.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Configurar documentación
builder.Services.ConfigureDocumentation(
    title: "Mi API",
    version: "v1",
    descripcion: "API para gestión de usuarios",
    name: "Soporte Técnico",
    email: "soporte@empresa.com",
    url: "https://empresa.com",
    requestExamples: new Dictionary<string, Dictionary<string, object>>
    {
        ["POST_/api/users"] = new Dictionary<string, object>
        {
            ["CrearUsuario"] = new { Name = "John Doe", Email = "john@example.com" }
        }
    },
    successExamples: new Dictionary<string, Dictionary<string, object>>
    {
        ["GET_/api/users"] = new Dictionary<string, object>
        {
            ["ListaUsuarios"] = new[] { new { Id = 1, Name = "Jane Doe" } }
        }
    }
);

📖 Documentación Generada

{
    "openapi": "3.0.4",
    "info": {
        "title": "Advance API DMS",
        "description": "API para el sistema advance",
        "contact": {
            "name": "Fredy Fuentes",
            "url": "https://www.dms.ms",
            "email": "fredy.fuentes@dms.ms"
        },
        "version": "1.0.0"
    },
    "servers": [
        {
          "url": "https://localhost:7253"
        },
        {
          "url": "http://localhost:5080"
        }
    ],
    "paths": {
        "/api/users": {
            post": {
            "tags": [
              "User"
            ],
            "requestBody": {
            "content": {
                "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/CrearUsuario"
                  },
                  "examples": {
                     "CrearUsuario": {
                        "value": {
                            "name": "John Doe",
                            "email": "john@example.com"
                        }
                     }
                  }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearUsuario"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CrearUsuario"
                },
                "examples": {
                  "ListaUsuarios": {
                    "value": [
                      {
                        "id": 1,
                        "name": "Jane Doe"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
        ...
}

🚀 Instalación

Puedes instalar el paquete desde NuGet con:

dotnet add package DMS.Documentation

🛠 Compatibilidad

• .NET 9.0+

📄 Documentación Completa

⚠️ Mejores Prácticas

• Ejemplos Reales: Usa datos que reflejen casos reales de uso.
• Documentación Completa: Describe cada endpoint y modelo de datos.
• Seguridad: Nunca expongas ejemplos con datos sensibles.
• Actualización: Mantén la documentación actualizada con cada cambio.

📄 Licencia

Este proyecto se encuentra bajo la licencia Apache2-0.

📌 Cómo Contribuir

Si deseas contribuir, revisa el archivo CONTRIBUTING.md para más detalles.

📜 Changelog

Para ver los cambios en cada versión, consulta el archivo CHANGELOG.md.