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

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

Общую документацию по 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

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

  1. 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]разделе "Ответ по умолчанию".

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute применяется к контроллеру — применяет указанный тип соглашения ко всем действиям на контроллере. Метод соглашения помечается подсказками, определяющими действия, к которым применяется метод соглашения. Дополнительные сведения о подсказках см. в разделе "Создание соглашений о веб-API").

    В следующем примере набор соглашений по умолчанию применяется ко всем действиям в ContactsConventionController:

    [ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{

  3. 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[] указывает на оставшиеся параметры, которые не должны быть явно сопоставлены.

Дополнительные ресурсы

  • Last updated on