{"id":13413,"date":"2018-12-12T17:06:27","date_gmt":"2018-12-12T19:06:27","guid":{"rendered":"http:\/\/gianfratti.com\/?p=13413"},"modified":"2018-12-12T17:16:02","modified_gmt":"2018-12-12T19:16:02","slug":"swagger-documente-seu-asp-net-web-api-rest","status":"publish","type":"post","link":"https:\/\/gianfratti.com\/index.php\/swagger-documente-seu-asp-net-web-api-rest\/","title":{"rendered":"Swagger \u2013 Documente seu ASP.NET Web API Rest"},"content":{"rendered":"

\"\"<\/a>
\nHoje meu post ir\u00e1 falar sobre como podemos documentar nossas API REST<\/strong>. Documentar nunca foi e nunca ser\u00e1 uma tarefa das mais legais geralmente \u00e9 mon\u00f3tono, cansativo e trabalhoso. Documenta\u00e7\u00e3o tende-se a se perder a longo do tempo e facilmente ficar desatualizado.<\/p>\n

E ai que surgiu o Swagger<\/strong>, ele \u00e9 um framework que automatiza a documenta\u00e7\u00e3o, com ele voc\u00ea pode descrever, consumir e visualizar sua API REST<\/strong>.\u00a0O interessante do Swagger\u00a0<\/strong>\u00e9 que ele mant\u00e9m sua documenta\u00e7\u00e3o sempre sincronizada tanto no lado cliente quanto no lado servidor j\u00e1 que ele est\u00e1 integrado diretamente ao c\u00f3digo.<\/p>\n

Swagger\u00a0<\/strong>\u00e9 um Framework multi linguagem e existem diversas implementa\u00e7\u00f5es nas mais diversas tecnologias e a sua implementa\u00e7\u00e3o para o ASP.NET Web API<\/strong> se chama \u201cSwashbuckle\u201d.\u00a0<\/strong>Essa implementa\u00e7\u00e3o facilita nossa vida j\u00e1 que basta adicionar o Swagger<\/strong> em qualquer projeto ASP.NET Web API<\/strong> e que como\u00a0um\u00a0passe de m\u00e1gica sua API<\/strong> ter\u00e1 uma documenta\u00e7\u00e3o maravilhosa. Outra coisa bem legal do Swagger\u00a0<\/strong>\u00e9 que ele n\u00e3o necessita de nenhuma depend\u00eancia ent\u00e3o basta adicionar o pacote via NuGet para habilitar a documenta\u00e7\u00e3o de sua API.<\/strong><\/p>\n

Ao instalar o pacote\u00a0Swagger <\/strong>com ele vem incorporado o Swagger-UI<\/strong> que basicamente \u00e9 uma interface que gera dinamicamente as documenta\u00e7\u00e3o da sua API<\/strong> e um Sandbox<\/strong> no qual podemos fazer os testes e a chamadas na nossa API<\/strong> e tudo isso de forma autom\u00e1tica.<\/p>\n

A figura abaixo mostra o Swagger<\/strong> e sua interface gr\u00e1fica<\/p>\n

\"\"<\/p>\n

A figura abaixo mostra o Sandbox do Swagger<\/strong> aonde podemos realizar os testes<\/p>\n

\"\"<\/a><\/p>\n

Utilizando o Swagger no ASP.NET Web Api<\/h4>\n

Para utilizar o Swagger<\/strong>, devemos adicionar o Swagger<\/strong> como depend\u00eancia do nosso projeto, o Swagger<\/strong> est\u00e1 dispon\u00edvel via NuGet. Execute o comando abaixo no Package Manager Console<\/strong><\/p>\n

Install-Package Swashbuckle\r\n\r\n<\/pre>\n
Com o pacote do Swagger<\/strong> instalado, ele ir\u00e1 criar uma arquivo de inicializa\u00e7\u00e3o (bootstrap) que est\u00e1 localizado em App_Start\/SwaggerConfig.cs.<\/p>\n
Agora com precisamos chamar o Swagger<\/strong> no processo de start up da nossa aplica\u00e7\u00e3o ent\u00e3o vamos abrir a WebApiConfig.cs<\/strong> e adicionar o c\u00f3digo abaixo<\/p>\n
\n
\n\n\n\n
\n
1<\/div>\n
2<\/div>\n
3<\/div>\n
4<\/div>\n
5<\/div>\n
6<\/div>\n
7<\/div>\n
8<\/div>\n
9<\/div>\n
10<\/div>\n
11<\/div>\n
12<\/div>\n
13<\/div>\n
14<\/div>\n
15<\/div>\n
16<\/div>\n
17<\/div>\n
18<\/div>\n
19<\/div>\n
20<\/div>\n<\/td>\n
\n
\n
namespace<\/code> Swagger<\/code><\/div>\n
{<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>public<\/code> static<\/code> class<\/code> WebApiConfig<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>{<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>public<\/code> static<\/code> void<\/code> Register(HttpConfiguration config)<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>{<\/code><\/div>\n
<\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>\/\/ Web API routes<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>config.MapHttpAttributeRoutes();<\/code><\/div>\n
<\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>config.Routes.MapHttpRoute(<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>name: <\/code>\"DefaultApi\"<\/code>,<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>routeTemplate: <\/code>\"api\/{controller}\/{id}\"<\/code>,<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>defaults: <\/code>new<\/code> { id = RouteParameter.Optional }<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>);<\/code><\/div>\n
<\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>SwaggerConfig.Register();<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>}<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>}<\/code><\/div>\n
}<\/code><\/div>\n<\/div>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n
Vamos agora habilitar o Swagger<\/strong> para que\u00a0use a documenta\u00e7\u00e3o gerada pelo XML Comments. Para isso devemos primeiro habilitar a gera\u00e7\u00e3o dos xml de documenta\u00e7\u00e3o.<\/p>\n
Vamos abrir a propriedades do projeto e marcar a op\u00e7\u00e3o XML documentation file <\/strong>na aba build<\/strong>, conforme figura abaixo<\/p>\n
\"\"<\/p>\n
Com a gera\u00e7\u00e3o de XML Comments habilitada, vamos colocar o Swagger<\/strong> para ler essa documenta\u00e7\u00e3o. Vamos abrir o SwaggerConfig.cs<\/strong> e adicionar o c\u00f3digo abaixo:<\/p>\n
\n
\n\n\n\n
\n
1<\/div>\n
2<\/div>\n
3<\/div>\n
4<\/div>\n
5<\/div>\n
6<\/div>\n
7<\/div>\n
8<\/div>\n
9<\/div>\n
10<\/div>\n
11<\/div>\n
12<\/div>\n
13<\/div>\n
14<\/div>\n
15<\/div>\n
16<\/div>\n
17<\/div>\n
18<\/div>\n
19<\/div>\n
20<\/div>\n
21<\/div>\n
22<\/div>\n
23<\/div>\n
24<\/div>\n
25<\/div>\n
26<\/div>\n<\/td>\n
\n
\n
namespace<\/code> Swagger<\/code><\/div>\n
{<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>public<\/code> class<\/code> SwaggerConfig<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>{<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>public<\/code> static<\/code> void<\/code> Register()<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>{<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>var<\/code> thisAssembly = <\/code>typeof<\/code>(SwaggerConfig).Assembly;<\/code><\/div>\n
<\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>GlobalConfiguration.Configuration <\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>.EnableSwagger(c =><\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>{<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>c.SingleApiVersion(<\/code>\"v1\"<\/code>, <\/code>\"Swagger Sample\"<\/code>);<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>c.IncludeXmlComments(GetXmlCommentsPath());<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>})<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>.EnableSwaggerUi(c =><\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>{<\/code><\/div>\n
<\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>});<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>}<\/code><\/div>\n
<\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>protected<\/code> static<\/code> string<\/code> GetXmlCommentsPath()<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>{<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>return<\/code> System.String.Format(<\/code>@\"{0}\\bin\\Swagger.XML\"<\/code>, System.AppDomain.CurrentDomain.BaseDirectory);<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>}<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>}<\/code><\/div>\n
}<\/code><\/div>\n<\/div>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n
Para o exemplo de nossa documenta\u00e7\u00e3o criei um simples Controller<\/strong> chamado Account<\/strong> e uma \u00fanica rota chamada Register<\/strong><\/p>\n
\n
\n\n\n\n
\n
1<\/div>\n
2<\/div>\n
3<\/div>\n
4<\/div>\n
5<\/div>\n
6<\/div>\n
7<\/div>\n
8<\/div>\n
9<\/div>\n
10<\/div>\n
11<\/div>\n
12<\/div>\n
13<\/div>\n
14<\/div>\n
15<\/div>\n
16<\/div>\n
17<\/div>\n
18<\/div>\n
19<\/div>\n
20<\/div>\n
21<\/div>\n
22<\/div>\n
23<\/div>\n
24<\/div>\n<\/td>\n
\n
\n
namespace<\/code> Swagger.Controllers<\/code><\/div>\n
{<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>[RoutePrefix(<\/code>\"api\/Account\"<\/code>)]<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>public<\/code> class<\/code> AccountController : ApiController<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>{<\/code><\/div>\n
<\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>\/\/\/ <summary><\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>\/\/\/ Register a new user on application<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>\/\/\/ <\/summary><\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>\/\/\/ <param name=\"user\">New user to register<\/param><\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>\/\/\/ <remarks>Adds new user to application and grant access<\/remarks><\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>\/\/\/ <response code=\"400\">Bad Request<\/response><\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>\/\/\/ <response code=\"500\">Internal Server Error<\/response><\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>[AllowAnonymous]<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>[Route(<\/code>\"Register\"<\/code>)]<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>[ResponseType(<\/code>typeof<\/code>(RegisterBindingModel))]<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>[HttpPost]<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>public<\/code> async<\/code> Task<IHttpActionResult> Register(RegisterBindingModel user)<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>{<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>\/\/IMPLEMENTATION OF CODE GOES HERE!!<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>throw<\/code> new<\/code> NotImplementedException();<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/code>}<\/code><\/div>\n
\u00a0\u00a0\u00a0\u00a0<\/code>}<\/code><\/div>\n
}<\/code><\/div>\n<\/div>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n
Veja agora o resultado quando executamos nossa aplica\u00e7\u00e3o<\/p>\n
\"\"<\/p>\n
Como podemos ver, o Swagger<\/strong> detalhou todo o nossa rota e colocou em sua interface gr\u00e1fica assim podemos saber para que serve, como\u00a0fazer a requisi\u00e7\u00e3o\u00a0e quais par\u00e2metros devemos passar.<\/p>\n
Com o Swagger<\/strong> podemos n\u00e3o somente detalhar melhor nossas API como tamb\u00e9m podemos customizar toda a interface, alterando cores, fontes, css e etc.<\/p>\n","protected":false},"excerpt":{"rendered":"
Hoje meu post ir\u00e1 falar sobre como podemos documentar nossas API REST. Documentar nunca foi e nunca ser\u00e1 uma tarefa das mais legais geralmente \u00e9 mon\u00f3tono, cansativo e trabalhoso. Documenta\u00e7\u00e3o tende-se a se perder a longo do tempo e facilmente ficar desatualizado.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_exactmetrics_skip_tracking":false,"_exactmetrics_sitenote_active":false,"_exactmetrics_sitenote_note":"","_exactmetrics_sitenote_category":0,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[2],"tags":[244,243],"class_list":["post-13413","post","type-post","status-publish","format-standard","hentry","category-net-framework","tag-documentacao","tag-swagger"],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/posts\/13413","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/comments?post=13413"}],"version-history":[{"count":7,"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/posts\/13413\/revisions"}],"predecessor-version":[{"id":13425,"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/posts\/13413\/revisions\/13425"}],"wp:attachment":[{"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/media?parent=13413"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/categories?post=13413"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/gianfratti.com\/index.php\/wp-json\/wp\/v2\/tags?post=13413"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}