Cómo hacer que WebAPI genere automáticamente documentación API en línea hermosa y práctica

1.1 SwaggerUI

SwaggerUI es una sencilla herramienta de prueba y documentación de Restful API. Sencillo, bonito y fácil de usar (demostración oficial). La API se muestra leyendo la configuración JSON. El proyecto en sí solo se basa en algunos archivos estáticos html, css.js. Puede usarlo en casi cualquier contenedor web.

1.2 Swashbuckle

Swashbuckle es una biblioteca de clases .NET que puede generar la configuración JSON correspondiente a SwaggerUI a partir de todos los métodos de controlador abiertos de WebAPI. Luego muéstrelo a través de SwaggerUI. SwaggerUI ya está incluido en la biblioteca de clases. Por lo que no se requiere ninguna instalación adicional.

2. Inicio rápido

Cree el proyecto OnlineAPI para encapsular Baidu Music Service (descarga de muestra). A través de la API, puede buscar, obtener información musical y conexiones de reproducción.

Intento eliminar algunos archivos que no se utilizarán en nuestra demostración para que parezca más simple.

Instalación de WebAPI Swashbuckle

Install-Package Swashbuckle

Los comentarios del código generan instrucciones de documentación.

Swashbuckle lee los comentarios del archivo XML generado y genera SwaggerUI e instrucciones en la configuración JSON.

Durante la instalación, se generará un archivo de configuración SwaggerConfig.cs en la carpeta App_Start del directorio del proyecto, que se utiliza para configurar los comportamientos de visualización relacionados con SwaggerUI. Como se muestra en la imagen:

Elimine los comentarios en aproximadamente 99 líneas del archivo de configuración y modifíquelo a

c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name)) ;

Y agregar un método en la clase actual

///

///

///

cadena estática protegida GetXmlCommentsPath(nombre de cadena)

{

return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, nombre);

}

Apretado Luego marca "archivo de documento XML" en la pestaña de generación de propiedades de este proyecto web, y el archivo de anotaciones de la biblioteca de clases se genera durante el proceso de compilación

Agrega tres Baidu Music API

Acceda a http:///swagger/ui/index, el efecto de visualización final

Probamos si la API se ejecuta correctamente a través de la API

3. Agregue un encabezado HTTP personalizado

Al desarrollar API móviles, a menudo es necesario verificar los permisos. Es mejor colocar parámetros de verificación en el encabezado de la solicitud HTTP. WebAPI se puede usar con filtros para verificar permisos

Primero necesitamos crear una clase con la interfaz IOperationFilter.

IOperationFilter

usando System;

usando System.Collections.Generic;

usando System.Linq;

usando System.Web;

usando System.Web.Http;

usando System.Web.Http.Description;

usando System.Web.Http.Filters;

usando Swashbuckle.Swagger;

espacio de nombres OnlineAPI.Utility

{

clase pública HttpHeaderFilter: IOperationFilter

{

public void Aplicar(Operación operación, SchemaRegistry

schemaRegistry, ApiDescription apiDescription)

{

if (operación.parametros == null) operación.parametros = nuevo

Lista();

var filterPipeline =

apiDescription.ActionDescriptor.GetFilterPipeline();

// Determine si se debe agregar un filtro de permiso

var isAuthorized = filterPipeline.Select(filterInfo =>

filterInfo.Instance).Any(filter => filter is IAuthorizationFilter);

//Determinar si se permiten métodos anónimos

var enableAnonymous =

apiDescription.ActionDescriptor.GetCustomAttributes().Any();

if ( isAuthorized && !allowAnonymous)

{

operación.parameters.Add(new Parameter

{

nombre = "acceso- clave" ,

@in = "encabezado",

descripción = "Clave de acceso de usuario",

requerido = falso,

tipo = "cadena"

})

;

}

}

}

}

Configure la clase de método anónimo en EnableSwagger en SwaggerConfig. cs Agregar una línea de código de registro

c.OperationFilter();

Agregar un filtro de permisos web

usando System;

usando System.Collections.Generic;

usando System.Linq;

usando System.Net;

usando System.Net.Http;

usando System.Text;

usando System.Web;

usando System.Web.Http;

usando System.Web.Http.Controllers ;

usando Newtonsoft.Json;

espacio de nombres OnlineAPI.Utility

{

///

clase pública AccessKeyAttribute : AuthorizeAttribute

{

// /

///

///

anulación protegida bool IsAuthorized(HttpActionContext actionContext)

{

var request = actionContext.Request ;

if (request.Headers.Contains("clave-de acceso"))

{

var accessKey = request.Headers. GetValues("access-key").SingleOrDefault();

//Clave de verificación TODO

return accessKey == "123456789";

}

return false;

}

///