Язык программирования C#9 и платформа .NET5

Троелсен Эндрю

using System.Reflection;

Файл XML-документации добавляется в Swagger вызовом метода

IncludeXmlComments

внутри метода

AddSwaggerGen

. Перейдите к методу

ConfigureServices

класса

Startup

и модифицируйте метод

AddSwaggerGen

, добавив файл XML-документации:

services.AddSwaggerGen(c =>

{

c.SwaggerDoc("v1",

new OpenApiInfo

{

Title = "AutoLot Service",

Version = "v1",

Description = "Service to support the AutoLot dealer site",

License = new OpenApiLicense

{

Name = "Skimedic Inc",

Url = new Uri("http://www.skimedic.com")

}

});

var xmlFile = $"{Assembly.GetExecutingAssembly.GetName.Name}.xml";

var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);

c.IncludeXmlComments(xmlPath);

});

Запустите

приложение и загляните в пользовательский интерфейс Swagger. Обратите внимание на XML-комментарии, интегрированные в пользовательский интерфейс Swagger (рис. 30.4).

Помимо XML-документации документирование может быть улучшено дополнительной конфигурацией конечных точек приложения.

Дополнительные возможности документирования для конечных точек API

Существуют дополнительные атрибуты, которые дополняют документацию Swagger. Чтобы применить их, начните с добавления показанных далее операторов

using

в файл

ValuesController.cs

:

using Microsoft.AspNetCore.Http;

using Swashbuckle.AspNetCore.Annotations;

Атрибут

Produces

задает тип содержимого для конечной точки. Атрибут

ProducesResponseType

использует перечисление

StatusCodes

для указания возможного кода возврата для конечной точки. Модифицируйте метод

Get

класса

ValuesController

, чтобы установить

application/json

в качестве возвращаемого типа и сообщить о том, что результатом действия будет либо 200 (ОК), либо 400 (Bad Request):

[HttpGet]

[Produces("application/json")]

[ProducesResponseType(StatusCodes.Status200OK)]

[ProducesResponseType(StatusCodes.Status400BadRequest)]

public ActionResult<IEnumerable<string>> Get

{

return new string[] {"value1", "value2"};

}

Хотя атрибут

ProducesResponseType

добавляет в документацию коды ответов, настроить эту информацию невозможно. К счастью, Swashbuckle добавляет атрибут

SwaggerResponse

, предназначенный как раз для такой цели. Приведите код метода

Get

к следующему виду:

[HttpGet]

[Produces("application/json")]

[ProducesResponseType(StatusCodes.Status200OK)]

[ProducesResponseType(StatusCodes.Status400BadRequest)]

[SwaggerResponse(200, "The execution was successful")]

[SwaggerResponse(400, "The request was invalid")]

public ActionResult<IEnumerable<string>> Get

{

return new string[] {"value1", "value2"};

}

Прежде чем аннотации Swagger будут приняты и добавлены в сгенерированную документацию, их потребуется включить. Откройте файл

Startup.cs

и перейдите к методу

Configure

. Обновите вызов

AddSwaggerGen

, как показано ниже:

services.AddSwaggerGen(c =>

{

c.EnableAnnotations;

...

});

Теперь, просматривая раздел ответов в пользовательском интерфейсе Swagger, вы будете видеть настроенный обмен сообщениями (рис. 30.5).

На заметку! В Swashbuckle поддерживается большой объем дополнительной настройки, за сведениями о которой обращайтесь в документацию по ссылке

https://github.com/domaindrivendev/Swashbuckle.AspNetCore

.

Построение методов действий API

Большинство функциональных средств приложения

AutoLot.Api

можно отнести к одному из перечисленных далее методов:

•

GetOne

•

GetAll

•

UpdateOne

•

AddOnе

•

DeleteOne

Основные методы API будут реализованы в обобщенном базовом контроллере API. Начните с создания нового каталога под названием

Base

в каталоге

Controllers

проекта

AutoLot.Api

. Добавьте в этот каталог новый файл класса по имени

BaseCrudController.cs

. Модифицируйте операторы

using

и определение класса, как демонстрируется ниже:

using System;

using System.Collections.Generic;

using AutoLot.Dal.Exceptions;

using AutoLot.Models.Entities.Base;

using AutoLot.Dal.Repos.Base;

using AutoLot.Services.Logging;

using Microsoft.AspNetCore.Http;

using Microsoft.AspNetCore.Mvc;

using Swashbuckle.AspNetCore.Annotations;

namespace AutoLot.Api.Controllers.Base