Gerar especificação de API REST com Swagger

A especificação OpenAPI Swagger está para os serviços RESTfull assim como a WSDL está para os webservices.

O Visual Studio 2017 tem suporte para a especificação e criação de proxys para API REST com o protocolo Swagger.

Pressupostos

Criação de projecto do tipo ASP.NET MVC Web API no Visual Studio 2017 para .NET Framework 4.6 com a template de fábrica.

Adição de documentação XML ao controller

Na pasta Controllers, é criado o controller ValuesController.cs por omissão. Nesta classe, substituir as acções pelo seguinte código:

private string[] lista
        {
            get
            {
                if (System.Web.HttpContext.Current.Application["lista"] == null)
                {
                    System.Web.HttpContext.Current.Application["lista"] = new string[] { "value1", "value2" };
                }
                return
                    (string[])System.Web.HttpContext.Current.Application["lista"];
            }
        }

        /// <summary>
        /// Retrieves the list of values
        /// </summary>
        /// <returns></returns>
        public IEnumerable<string> Get()
        {
            return lista;
        }
        /// <summary>
        /// Retrieves one value from the list of values
        /// </summary>
        /// <param name="id">The id of the item to be retrieved</param>
        /// <returns></returns>
        public string Get(int id)
        {
            return lista[id];
        }
        /// <summary>
        /// Insert a new value in the list
        /// </summary>
        /// <param name="value">New value to be inserted</param>
        public void Post([FromBody]string value)
        {
        }
        /// <summary>
        /// Change a single value in the list
        /// </summary>
        /// <param name="id">The id of the value to be changed</param>
        /// <param name="value">The new value</param>
        public void Put(int id, [FromBody]string value)
        {
            lista[id] = value;
        }
        /// <summary>
        /// Delete an item from the list
        /// </summary>
        /// <param name="id">id of the item to be deleted</param>
        public void Delete(int id)
        {

        }

Ao executar a aplicação para depuração é apresentada a página inicial no navegador pré-definido.
Na barra de endereços do navegador, escrever o caminho para o controller Values.

<url base>/api/values

A API REST devolve o resultado da lista:

["value1","value2"]

Integração do Swagger no projecto

O protocolo Swagger é agnóstico. Portanto, é necessária uma ferramenta para implementação do protocolo em função da tecnologia. A ferramenta para .NET é o SwashBuckle. Existem duas versões, a Swashbuckle.Net45 para .NET Framework 4.5 e posteriores e outra para as mais antigas.

Na Consola de Gestão de Pacotes NuGet procede-se à instalação da última versão do pacote Swashbuckle.Net45, tendo este projecto da WebApi como padrão

PM> Install-Package Swashbuckle.Net45 -Version 5.2.1

Configuração da documentação XML

O SwashBuckle usa a documentação XML para descrever as acções das APIs. Para isso há que seleccionar as propriedades do projecto e no separador Build indicar o ficheiro de output para documentação XML. Exemplo: \bin\myWebApi.xml

Configuração do SwashBuckle

Procurar o ficheiro SwaggerConfig.cs na pasta App_Start do projecto da WebApi.
Descomentar a seguinte linha de código do método Register

c.IncludeXmlComments(GetXmlCommentsPath());

Gerar o método GetXmlCommentsPath com uma instrução idêntica à do exemplo seguinte

protected static string GetXmlCommentsPath()
          {
              return System.String.Format(@"{0}\bin\myWebApi.xml", 
                  System.AppDomain.CurrentDomain.BaseDirectory);
          }

Visualização da página de documentação Swagger

Voltar a executar a WebApi.
Ao executar a aplicação para depuração é apresentada a página inicial no navegador pré-definido.
Na barra de endereços do navegador, escrever o caminho para a documentação Swagger.

<url base>/Swagger/ui/index

O Swagger usa a documentação XML de cada operação:

Lista de operações da classe ValueController.cs

Especificação da interface da acção Get da API REST

Bootstrap Slider

Referências: Visual Studio 2017 and Swagger: Building and Documenting Web APIs, GitHub Swashbuckle Project

Licença CC BY-SA 4.0 Silvia Pinhão Lopes, 12.10.17