DEV Community

loading...
Cover image for Creando un API en Net Core 5 - OpenAPI & Swagger

Creando un API en Net Core 5 - OpenAPI & Swagger

andreslozadamosto profile image Andres Lozada Mosto 銉5 min read

Hi there! 馃憢

Lleg贸 una nueva parte de esta gu铆a de creaci贸n de APIs en NetCore.

En este art铆culo veremos c贸mo incluir OpenAPI en nuestro proyecto.

Si quieren ver el resultado final ejecut谩ndose, pueden bajarlo del github

Vamos?


驴Qu茅 es OpenAPI?

OpenAPI (que ya fue mencionada en nuestro segundo art铆culo) es un est谩ndar que predefine como describir o documentar nuestro API.

Dejando detalles de lado, OpenAPI define debe existir un archivo en formato JSON o YAML en donde se definan todos lo recursos del API, acciones que se le pueden realizar, informaci贸n que se debe enviar a cada endpoint y que se puede recibir, etc.

En definitiva, regula todo el aspecto de como escribir ese archivo y por consiguiente, define la forma de documentar nuestro API para que otro equipo/persona sepa c贸mo utilizarlo.

驴Qu茅 es Swagger?

Swagger es un proyecto open source que implementa el est谩ndar. El proyecto fue cedido a la Open API Initiative y desde ese momento se transforman en sin贸nimos.

Hay que diferenciar que uno es el est谩ndar y el otro (Swagger) es una implementaci贸n y creaci贸n del UI en base al archivo JSON/YAML generado.

Alternativas

En cuanto a especificaciones, tenemos a RAML.

Para reemplazar el UI, tenemos alternativas en donde se destaca Redoc.

En este link podemos ver un listado de opciones al UI de Swagger.


Agregar OpenAPI y Swagger UI a nuestro API

En mundo de .Net Core hay 2 librer铆as principales, Swashbuckle y NSwag. En este caso vamos a utilizar Swashbuckle que es la que desde .Net 5 viene incluida por defecto en el template de APIs

Librer铆as

Agregamos el siguiente paquete de Nuget

$> dotnet add package Swashbuckle.AspNetCore
Enter fullscreen mode Exit fullscreen mode

Configurando el Startup.cs

Debemos agregar unas l铆neas en las funciones ConfigurationServices

services.AddSwaggerGen();
Enter fullscreen mode Exit fullscreen mode

Y en Configure

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
Enter fullscreen mode Exit fullscreen mode

Customizaciones

SwaggerUIPodemos agregar informaci贸n a la documentaci贸n, agregar nuestros propios archivos _css y javascript para personalizar la pantalla.

Documentaci贸n de XMLDocs

Podemos utilizar nuestra documentaci贸n de c贸digo por medio de XML Docs para mostrar informaci贸n en el UI.

Primero debemos indicarle al proyecto que genere el archivo XML con los comentarios de las funciones

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
Enter fullscreen mode Exit fullscreen mode

Luego le decimos a Swagger que cargue el archivo

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { 
        Title = "My First Net Core REST API",
        Version = "v1"
    });

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});
Enter fullscreen mode Exit fullscreen mode

Alt Text

Logo customizado

Podemos agregar customizaciones a la UI para que se adapte a la gr谩fica de nuestra empresa. Para eso podemos agregar archivos CSS, Javascript o bien utilizar un HTML completo personalizado.

Para los cambios b谩sicos (cambio de logo y color del header) solo necesitaremos agregar un CSS nuevo de la siguiente manera

app.UseStaticFiles();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "MyFirstNetCoreWebAPI.WebAPI v1");
    c.InjectStylesheet("/swagger-ui/swagger-custom.css");
});
Enter fullscreen mode Exit fullscreen mode

y el archivo css dentro de una nueva carpeta que llamaremos wwwroot

.swagger-ui .topbar {
    background-color: #1abc9c;
}

.topbar-wrapper a img[alt="Swagger UI"] {
    display: none;
}

.topbar-wrapper a {
    display: block;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
    background: url(apilogo.png) no-repeat;
    width: 300px; /* Width of new image */
    height: 86px; /* Height of new image */
    padding-left: 180px; /* Equal to width of new image */
}


.topbar-wrapper .select-label span {
    color: #212121;
}
Enter fullscreen mode Exit fullscreen mode

El previo css nos provee este bonito resultado.

Alt Text

Informaci贸n de licencia y autor铆a

Otra cosa que podemos agregar e importante cuando la API es p煤blica es la informaci贸n de Autor铆a y Licencia.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { 
        Title = "My First Net Core REST API",
        Version = "v1",
        Description = "A simple example ASP.NET Core Web API by Andr茅s Lozada Mosto, You can find this tutorial here: https://dev.to/andreslozadamosto/creando-un-api-en-net-core-5-intro-2nc2",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Andres Lozada Mosto",
            Email = string.Empty,
            Url = new Uri("https://github.com/andreslozadamosto"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under MIT licence",
            Url = new Uri("https://choosealicense.com/licenses/mit/"),
        }
    });
});
Enter fullscreen mode Exit fullscreen mode

Definiendo datos requeridos

Podemos utilizar los atributos como [required] para indicar cu谩les datos son requeridos por el objeto recibido como par谩metro

Alt Text

Tipo de salida

Algo muy importante es indicar al p煤blico target que utilizar谩 nuestro API el formato en que recibir谩 las respuestas. Esto se realiza indicando el MIME TYPE devuelto por el Action del Controller.

[Produces("application/json")]
Enter fullscreen mode Exit fullscreen mode

Este atributo lo podemos utilizar a nivel de Clase como de Action Method.

Como veremos en art铆culos posteriores, cuando se llama a un API desde un frontend en javascript 茅ste le puede indicar que formato de tipo de respuesta le gustar铆a recibirf_JSON_, XML, otro). Net Core provee soporte a esta funcionalidad y se pueden registrar cualquier tipo de formarteadores de salida. Pero este tema lo veremos en mayor profundidad en pr贸ximos art铆culos.

C贸digos de HTTP de respuesta [ProducesResponseType]

Otra informaci贸n muy relevante por los usuarios de nuestra API es conocer cuales son los c贸digos HTTP de respuesta que podemos obtener al realizar un request.

Para documentar esto utilizamos el siguiente atributo a nivel de Action Method

[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status409Conflict)]
[ProducesResponseType(StatusCodes.Status201Created)]
Enter fullscreen mode Exit fullscreen mode

El enum StatusCodes tiene enumerados para todos los diferentes c贸digos de respuesta HTTP.

En el UI queda desglosado las diferentes posibles respuestas
Alt Text


Extra

Hay un mundo de librer铆as que podemos utilizar junto con Open API tales como generadores de librer铆as cliente (para consumir nuestro API desde cualquier lenguaje), generadores de server stubs, chequeo de seguridad entre otros.

Esta web https://openapi.tools nos provee un gran listado de herramientas organizadas por tema.


Discussion (0)

pic
Editor guide