Использование соглашений веб-API

Статья
11/30/2023

Общую документацию по API можно извлечь и применить к нескольким действиям, контроллерам или всем контроллерам в сборке. Соглашения веб-API заменяют применение атрибута [ProducesResponseType] к отдельным действиям.

Соглашение позволяет следующее.

Определять наиболее распространенные типы возврата и коды состояния, возвращаемые из определенного типа действия.
Выявлять действия, отличающиеся от определенного стандарта.

Соглашения по умолчанию доступны из Microsoft.AspNetCore.Mvc.DefaultApiConventions. Соглашения демонстрируются с ValuesController.cs добавлением в шаблон проекта API :

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

namespace WebApp1.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        [HttpGet("{id}")]
        public ActionResult<string> Get(int id)
        {
            return "value";
        }

        // POST api/values
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }

        // PUT api/values/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
        }

        // DELETE api/values/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }
}

Действия, которые следуют шаблонам в ValuesController.cs работе с соглашениями по умолчанию. Если соглашения по умолчанию не соответствуют вашим потребностям, см. раздел Создание соглашений веб-API.

Во время выполнения Microsoft.AspNetCore.Mvc.ApiExplorer понимает соглашения. ApiExplorer является абстракцией MVC для взаимодействия с генераторами документов OpenAPI (также называется Swagger). Атрибуты из примененного соглашения связываются с действием и включаются в документацию OpenAPI для действия. Анализаторы API также понимают соглашения. Если ваше действие является нестандартным (например, возвращает код состояния, который не задокументирован примененным соглашением), выводится предупреждение, позволяющее задокументировать код состояния.

Просмотреть или скачать образец кода (описание загрузки)

Применение соглашений веб-API

Соглашения не являются составными, каждое действие может быть связано только с одним соглашением. Более конкретные соглашения имеют приоритет над менее определенными. Если к действию применяются два или более соглашения с одинаковым приоритетом, выбор осуществляется недетерминированным образом. Существуют следующие варианты применения соглашения к действию (от наиболее конкретного до наименее конкретного):

Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — применяется к отдельным действиям и указывает тип соглашения и метод соглашения, который применяется.

В следующем примере метод соглашения Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put типа соглашения по умолчанию применяется к действию Update:
```
// PUT api/contactsconvention/{guid}
[HttpPut("{id}")]
[ApiConventionMethod(typeof(DefaultApiConventions), 
                     nameof(DefaultApiConventions.Put))]
public IActionResult Update(string id, Contact contact)
{
    var contactToUpdate = _contacts.Get(id);

    if (contactToUpdate == null)
    {
        return NotFound();
    }

    _contacts.Update(contact);

    return NoContent();
}
```
Метод соглашения Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put применяет следующие атрибуты к действию:
```
[ProducesDefaultResponseType]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
```
Дополнительные сведения о [ProducesDefaultResponseType] см. в описании ответа по умолчанию.
Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute применяется к контроллеру — применяет указанный тип соглашения ко всем действиям на контроллере. Метод соглашения снабжен указаниями, определяющими действия, к которым применяется метод соглашения. Дополнительные сведения об указаниях см. в разделе Создание соглашений веб-API.

В следующем примере набор соглашений по умолчанию применяется ко всем действиям в ContactsConventionController:
```
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
```
Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute применяется к сборке— применяет указанный тип соглашения ко всем контроллерам в текущей сборке. В качестве рекомендации примените атрибуты уровня сборки Startup.cs в файле.

В следующем примере набор соглашений по умолчанию применяется ко всем контроллерам в сборке:
```
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
    public class Startup
    {
```

Создание соглашений веб-API

Если соглашения API по умолчанию не соответствуют вашим потребностям, создайте собственные соглашения. Соглашение:

Это статический тип с методами.
Может определять типы ответов и требования к именованию для действий.

Типы ответов

Эти методы помечаются атрибутами [ProducesResponseType] или [ProducesDefaultResponseType]. Например:

public static class MyAppConventions
{
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public static void Find(int id)
    {
    }
}

Если отсутствуют более конкретные атрибуты метаданных, применение этого соглашения к сборке указывает, что:

Метод соглашение применяется к любому действию с именем Find.
Параметр с именем id присутствует для действия Find.

Требования к именам

Атрибуты [ApiConventionNameMatch] и [ApiConventionTypeMatch] можно применить к методу соглашения, определяющему действия, к которым они применяются. Например:

[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
public static void Find(
    [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Suffix)]
    int id)
{ }

В предыдущем примере:

Параметр Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix, примененный к методу, указывает, что соглашение соответствует любому действию с префиксом Find. Примеры соответствующих действий: Find, FindPet и FindById.
Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix, примененный к параметру, указывает, что соглашение соответствует методам только с одним параметром, заканчивающимся на идентификатор суффикса. Это такие параметры, как id или petId. ApiConventionTypeMatch может аналогичным образом применяться к типам для ограничения типа параметра. Аргумент params[] указывает на остальные параметры, которым не требуется явное сопоставление.

Поделиться через