Esta publicación fue editada por última vez por QWERTYU el 12-4-2019 a las 14:24
IntroducciónDespués de usar asp.net Core para el desarrollo de APIs, escribir documentación API debe ser una tarea dolorosa para los programadores, pero la documentación debe escribirse, y si no hay requisitos específicos para el formato de la documentación, la documentación final depende totalmente del estado de ánimo del desarrollador. O ser más detallado o más sencillo. ¿Existe una forma rápida y eficiente de crear la documentación de la API? La respuesta es sí, ¡Swagger es una de las herramientas más populares para generar documentación de APIs REST!
¿Por qué usar Swagger como herramienta de generación de documentación de APIs REST?- Swagger puede generar una consola interactiva de APIs que los desarrolladores pueden usar para aprender y experimentar rápidamente con APIs.
- Swagger puede generar código del SDK cliente para implementaciones en una variedad de plataformas diferentes.
- Los archivos Swagger pueden generarse automáticamente a partir de comentarios de código en muchas plataformas diferentes.
- Swagger tiene una comunidad sólida con muchos colaboradores destacados.
¿Cómo usar Swagger para generar documentación de API en asp.net núcleo?- Swashbuckle.AspNetCore es un proyecto de código abierto que genera documentación de Swagger para ASP.NET API web Core.
- NSwag es otro proyecto de código abierto para integrar Swagger UI o ReDoc en ASP.NET APIs Web Core. Proporciona una forma de generar código cliente en C# y TypeScript para APIs.
A continuación se muestra un ejemplo de Swashbuckle.AspNetCore¿Cuáles son los componentes de un Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Expone el objeto SwaggerDocument como modelo de objetos Swagger y middleware para endpoints JSON.
- Swashbuckle.AspNetCore.SwaggerGen: Un generador de Swagger que genera objetos SwaggerDocument directamente a partir de rutas, controladores y modelos. A menudo se combina con el middleware de endpoint de Swagger para exponer automáticamente el JSON de Swagger.
- Swashbuckle.AspNetCore.SwaggerUI: Una versión integrada de la herramienta Swagger UI. Interpreta Swagger JSON para crear experiencias personalizables y ricas que describan la funcionalidad de las APIs web. Incluye herramientas de prueba integradas para métodos comunes.
¿Cómo instalar Swashbuckle con vs2017?
La primera manera: instalar desde la ventana de la Consola del Gestor de Paquetes
- Ve a Vistas > otras consolas del gestor de paquetes de Windows >
- Navega al directorio que contiene el archivo TodoApi.csproj
- Por favor, ejecute la siguiente orden · Install-Package Swashbuckle.AspNetCore
-
Segunda forma: Desde el cuadro de diálogo Gestionar paquetes NuGet:- Haz clic derecho en el proyecto en el Explorador de Soluciones > Gestionar paquetes NuGet
- Configurar el código fuente del paquete a nuget.org
- Escribe "Swashbuckle.AspNetCore" en la caja de búsqueda
- Selecciona el paquete Swashbuckle.AspNetCore en la pestaña Explorar y haz clic en Instalar
-
Añadir y configurar el middleware de SwaggerIntroduce primero el espacio de nombres: Añade el generador Swagger a la colección de servicios en el método Startup.ConfigureServices: enInicio.Configuremétodo, habilitar middleware para servir el documento JSON generado y la interfaz de usuario Swagger:
Abre la app y navega hasta ellahttps://localhost:<port>/swagger/v1/swagger.json。 La documentación resultante que describe el endpoint se muestra en formato JSON de la siguiente manera.
Disponiblehttps://localhost:<port>/confianzaLocaliza la interfaz de Swagger. Consulta la documentación de la API a través de la interfaz de Swagger como se muestra a continuación.
Para aplicar la raíz (http://localhost:<port>/) para proporcionar la interfaz de Swagger, por favor ponga elPrefijo de RutaLa propiedad se establece en una cadena vacía:
Uso avanzado de Swagger (personalización y extensiones)Utiliza Swagger para añadir información explicativa a la documentación de la APILas siguientes operaciones de configuración se realizan en el método AddSwaggerGen, que añade información como el autor, la licencia y la descripción: La información sobre la versión de visualización de la interfaz de usuario de wagger se muestra en la siguiente figura: Añadir comentarios a los métodos de interfazPrimero hagamos clic en la API, ampliemos como se muestra en la figura de abajo, ¿no puede haber comentarios? ¿Cómo añadir comentarios? Añadir comentarios en el documento con tres o como se muestra en la imagen de abajo, como se muestra más abajo Luego ejecuta el proyecto y vuelve a la interfaz de sombría para ver si aparece el comentario Aún no aparecía, no te preocupes, ¡mira hacia abajo! Habilitar anotaciones XMLPuedes habilitar anotaciones XML usando los siguientes métodos: - Haz clic derecho en el proyecto en el Explorador de Soluciones y selecciona Propiedades
- Mira el cuadro de archivo de documento XML bajo la sección de Salida de la pestaña de Compilación
-
Habilitar anotaciones XML proporciona información de depuración para tipos y miembros comunes no documentados. Si aparecen muchos mensajes de advertencia, por ejemplo, el siguiente mensaje indica una violación del código de advertencia 1591:
¿Y si tienes TOC y quieres cancelar la advertencia? Puedes cancelar como se muestra en la imagen de abajo
Observa la ruta del archivo de documento xml generado arriba,
Nota: 1. Para sistemas operativos Linux o no Windows, los nombres y rutas de archivo son sensibles a mayúsculas y minúsculas. Por ejemplo, un archivo "SwaggerDemo.xml" funciona en Windows, pero no en CentOS. 2. Para obtener la ruta de aplicación, se recomienda usar AppContext.BaseDirectory para obtenerla Reconstruye y ejecuta el proyecto para ver si aparecen los comentarios A partir de la operación anterior, se puede resumir que la interfaz de Swagger muestra el <summary> texto interno de los elementos del código de comentario anterior como comentarios grandes de la API. Por supuesto, también puedes añadir el elemento de comentarios a la documentación de Obtención de instrucciones. Puede complementar <summary> la información especificada en el elemento y proporcionar una interfaz de Swagger más fiable. <remarks> El contenido de Element puede contener texto, JSON o XML. El código es el siguiente: Prueba la interfaz de la API usando SwaggerUIDepuremos la interfaz a través de SwaggerUI con un pequeño ejemplo
- Haz clic en una interfaz API que necesite ser probada y luego haz clic en el botón "Pruébalo" a la izquierda y derecha de Parámetros
- Introduce un parámetro en el cuadro de texto del parámetro que aparece, como se muestra en la imagen siguiente, introduce el parámetro 2
- Haz clic en el botón Ejecutar y aparecerá la Respuesta formateada que se muestra a continuación, como se muestra en la figura siguiente
Bueno, eso es todo por el tutorial de hoy sobre cómo usar Swagger para generar documentación de la API en ASP.NET Core WebApi. ¡Espero que te sea útil aprender a usar Swagger para generar documentación de API en ASP.NET Core! resumenEste artículo comienza con el punto problemático de escribir la documentación de la API a mano, y luego lleva a Swagger, una herramienta que genera automáticamente documentación de la API. Luego, mediante texto e imágenes fáciles de entender, demostraremos cómo usar SwaggerUI para generar documentación de API en una ASP.NET Core WebApi. Por último, ¡presentaré algunos usos avanzados de Swagger en ASP.NET Core! ¡Espero que te ayude a usar Swagger en ASP.NET Core!
| 
Publicado en 12/4/2019 14:14:46
|
|
|
|
