swagger lightning talk
TRANSCRIPT
SWAGGER
Documentando APIs desde
tempos imemoriais
A documentação de serviços GERALMENTE é um tédio
3
O que é swagger?
• Uma interface ao serviço.
• É um contrato para o teu serviço.
• É uma forma de descrever uma API.
4
Objetivo
• Estabelecer uma interface para APIs Rest independeente da linguagem.
• Que permita aos seres humanos e computadores descobrir e compreender as capacidades do serviço sem acesso ao código fonte, documentação, ou rede inspeção de tráfego-through.
• Quando adequadamente definido Swagger, um consumidor pode compreender e interagir com o serviço remoto com uma quantidade mínima de lógica de implementação.
5
Para que serve?
• Documentação interativa.
• Descrição de todo o que o server pode fazer.
• Criar contratos.
• Interagir com o serviço remoto.
6
Swagger UI
7
Editor Swagger
8
Antepassados
• CORBA
• WSDL
• WADL
9
Outras ferramentas atuais
• RAML
• API Blueprint
• entre outros...
10
Comparação
11
Comparação
RAML SWAGGER API BLUEPRINT
Escrever YAML JSON/YAML Markdown
Ferramenta de edição
Designer de API Editor Swagger -
Facilidade para começar
Muito facil, tudo esta no github
Tudo esta no github Requer instalação
Gerador de Documentação
Uma página ou multipágina (só php)
Uma página Uma página ou multipágina
Linguagens JS, Java, Node, PHP, Python, Ruby
Clojure, Go, JS, Java, .Net, Node, PHP, Python, Ruby, Scala
Node, .Net
12
Comparação
13
Swagger no Tech Radar
14
Links
• http://www.slideshare.net/fehguy/swagger-foryourapi
• http://www.slideshare.net/fehguy/introducing-swagger
• http://www.mikestowe.com/2014/07/raml-vs-swagger-vs-api-blueprint.php
• http://www.mikestowe.com/2014/12/api-spec-comparison-tool.php
• http://swagger.io/
• https://github.com/swagger-api/
• http://www.thoughtworks.com/radar/tools
