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

Использование соглашений веб-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 — применяется к отдельным действиям и указывает тип соглашения и метод соглашения, который применяется.

    В следующем примере к действию применяется Update метод соглашения типа Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put соглашения по умолчанию:

    // 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 по умолчанию не соответствуют вашим потребностям, создайте собственные соглашения. Соглашение:

Response types

Эти методы аннотированы или [ProducesResponseType][ProducesDefaultResponseType] атрибуты. For example:

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

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

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

Naming requirements

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

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

Additional resources