{"id":753,"date":"2016-05-12T06:00:57","date_gmt":"2016-05-12T09:00:57","guid":{"rendered":"https:\/\/www.erudio.com.br\/blog\/?p=753"},"modified":"2022-12-21T11:12:52","modified_gmt":"2022-12-21T14:12:52","slug":"documentando-aplicacoes-restfull-com-springboot-e-swagger","status":"publish","type":"post","link":"https:\/\/www.erudio.com.br\/blog\/documentando-aplicacoes-restfull-com-springboot-e-swagger\/","title":{"rendered":"Documentando aplica\u00e7\u00f5es REST com SpringBoot e Swagger"},"content":{"rendered":"

O Swagger<\/strong> \u00e9 um dos frameworks mais usados para se documentar API’s REST<\/strong>. Ele facilita para que os clientes que consomem nossas API’s<\/strong> saibam quais os par\u00e2metros nossas opera\u00e7\u00f5es recebem, qual o retorno, o modelo, o media type retornado JSON<\/strong>, XML<\/strong>, CSV<\/strong>, bin\u00e1rio etc. Sendo assim os clientes n\u00e3o precisam necessariamente discutir com a equipe de desenvolvimento da API<\/strong> sobre como us\u00e1-la. Pode-se dizer que a grosso modo o Swagger<\/strong> se comporta como o velho WSDL<\/strong> das aplica\u00e7\u00f5es SOAP<\/strong>. Sendo assim esse framework valoriza e muito nossas aplica\u00e7\u00f5es.<\/p>\n

Tomando como base o projeto do post anterior vamos adicionar as configura\u00e7\u00f5es necess\u00e1rias para habilitar o Swagger<\/strong> na aplica\u00e7\u00e3o. Para isso abra o arquivo pom.xml<\/strong> e adicione as tags destacadas com coment\u00e1rios no c\u00f3digo abaixo.<\/p>\n

\n<project xmlns="http:\/\/maven.apache.org\/POM\/4.0.0" xmlns:xsi="http:\/\/www.w3.org\/2001\/XMLSchema-instance" xsi:schemalocation="http:\/\/maven.apache.org\/POM\/4.0.0 http:\/\/maven.apache.org\/xsd\/maven-4.0.0.xsd">\n\t<modelversion>4.0.0<\/modelversion>\n\n\t<groupid>br.com.erudio<\/groupid>\n\t<artifactid>simple-rest-example-swagger<\/artifactid>\n\t<version>0.0.1-SNAPSHOT<\/version>\n\n    <parent>\n        <groupid>org.springframework.boot<\/groupid>\n        <artifactid>spring-boot-starter-parent<\/artifactid>\n        <version>1.3.3.RELEASE<\/version>\n    <\/parent>\n\n    <dependencies>\n\n        <dependency>\n            <groupid>org.springframework.boot<\/groupid>\n            <artifactid>spring-boot-starter-web<\/artifactid>\n        <\/dependency>\n\n    \t<!-- Adicionando a dependencia do Spring Boot Starter Actuator -->\n    \t<dependency>\n\t\t\t<groupid>org.springframework.boot<\/groupid>\n\t\t\t<artifactid>spring-boot-starter-actuator<\/artifactid>\n\t\t<\/dependency>\n\n\t\t<!-- Adicione as depend\u00eancias do Swagger API necess\u00e1rias para gerar a documenta\u00e7\u00e3o da aplica\u00e7\u00e3o-->\n\t\t<dependency>\n\t\t\t<groupid>com.mangofactory<\/groupid>\n\t\t\t<artifactid>swagger-springmvc<\/artifactid>\n\t\t\t<version>1.0.0<\/version>\n\t\t<\/dependency>\n\t\t<dependency>\n\t\t\t<groupid>org.ajar<\/groupid>\n\t\t\t<artifactid>swagger-spring-mvc-ui<\/artifactid>\n\t\t\t<version>0.4<\/version>\n\t\t<\/dependency>\n\t\t<dependency>\n    \t\t<groupid>org.apache.tomcat.embed<\/groupid>\n    \t\t<artifactid>tomcat-embed-jasper<\/artifactid>\n    \t\t<scope>provided<\/scope>\n\t\t<\/dependency>\n\n    <\/dependencies>\n\n    <properties>\n        <java.version>1.8<\/java.version>\n    <\/properties>\n\n    <build>\n        <plugins>\n            <plugin>\n                <groupid>org.springframework.boot<\/groupid>\n                <artifactid>spring-boot-maven-plugin<\/artifactid>\n            <\/plugin>\n        <\/plugins>\n    <\/build>\n\n    <repositories>\n        <repository>\n            <id>spring-releases<\/id>\n            <url>https:\/\/repo.spring.io\/libs-release<\/url>\n        <\/repository>\n\n   \t\t<!-- Adicione o reposit\u00f3rio do Swagger ao projeto-->\n\t\t<repository>\n\t\t\t<id>jcenter-release<\/id>\n\t\t\t<name>jcenter<\/name>\n\t\t\t<url>http:\/\/oss.jfrog.org\/artifactory\/oss-release-local\/<\/url>\n\t\t<\/repository>\n    <\/repositories>\n\n    <pluginrepositories>\n        <pluginrepository>\n            <id>spring-releases<\/id>\n            <url>https:\/\/repo.spring.io\/libs-release<\/url>\n        <\/pluginrepository>\n    <\/pluginrepositories>\n\n<\/project>\n<\/pre>\n
Feito isto precisamos alterar a classe Application<\/strong> para que ela acione o Swagger<\/strong> quando inicializar a aplica\u00e7\u00e3o.<\/p>\n
\npackage br.com.erudio;\n\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.boot.autoconfigure.EnableAutoConfiguration;\nimport org.springframework.boot.builder.SpringApplicationBuilder;\nimport org.springframework.context.annotation.Bean;\nimport org.springframework.context.annotation.ComponentScan;\nimport org.springframework.context.annotation.Configuration;\n\nimport com.mangofactory.swagger.configuration.SpringSwaggerConfig;\nimport com.mangofactory.swagger.models.dto.ApiInfo;\nimport com.mangofactory.swagger.plugin.EnableSwagger;\nimport com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;\n\n@Configuration \/\/ Define a classe como classe de configura\u00e7\u00e3o\n@EnableAutoConfiguration \/\/ Habilita a autoconfigura\u00e7\u00e3o\n@EnableSwagger \/\/Habilita o Swagger\n@ComponentScan(basePackages = {"br.com.erudio"}) \/\/Escaneia todos os pacotes com o padr\u00e3o br.com.erudio\npublic class Application {\n\n\t\/\/Injeta uma instancia de SpringSwaggerConfig\n    @Autowired\n    private SpringSwaggerConfig swaggerConfig;\n\n    public static void main(String[] args) {\n\t\t   \/\/Troque esta linha SpringApplication.run(Application.class, args); pela linha abaixo\n           new SpringApplicationBuilder(Application.class).web(true).run(args);\n    }\n\n    @Bean\n    public SwaggerSpringMvcPlugin groupOnePlugin() {\n       return new SwaggerSpringMvcPlugin(swaggerConfig)\n\t\t\t\/\/Adiciona as configura\u00e7\u00f5es do Swagger ao SwaggerSpringMvcPlugin\n           .apiInfo(apiInfo()) \/\/Adiciona as propriedades de configura\u00e7\u00e3o\n           .includePatterns("\/person.*?", "\/greeting.*?") \/\/Habilita o Swagger para os nossos 2 endpoints\n           .swaggerGroup("admin");\n    }\n\n    private ApiInfo apiInfo() {\n       ApiInfo apiInfo = new ApiInfo( \/\/Configura\u00e7\u00f5es de contato, licen\u00e7a etc n\u00e3o nescess\u00e1riamente precisa ser definida\n             "Swagger With Spring Boot",\n             "This is a simple application to demonstrate how to work with Swagger in Spring Boot project!",\n             "Free to use and mess around",\n             "erudio@gmail.com",\n             "Open Licence",\n             "myemail@gmail.com"\n       );\n       return apiInfo;\n    }\n}\n<\/pre>\n
Agora que o Swagger<\/strong> j\u00e1 est\u00e1 configurado vamos documentar o endpoint Greeting<\/strong>.<\/p>\n
\npackage br.com.erudio.web.controllers;\n\nimport java.util.concurrent.atomic.AtomicLong;\n\nimport org.springframework.http.HttpStatus;\nimport org.springframework.http.MediaType;\nimport org.springframework.web.bind.annotation.RequestMapping;\nimport org.springframework.web.bind.annotation.RequestMethod;\nimport org.springframework.web.bind.annotation.RequestParam;\nimport org.springframework.web.bind.annotation.ResponseStatus;\nimport org.springframework.web.bind.annotation.RestController;\n\nimport com.wordnik.swagger.annotations.Api;\nimport com.wordnik.swagger.annotations.ApiOperation;\n\nimport br.com.erudio.models.Greeting;\n\n@Api(value = "greeting") \/\/Diz ao Swagger que esse \u00e9 um endpoint e REST deve ser documentado\n@RestController\n@RequestMapping("\/greeting")\npublic class GreetingController {\n\n    private static final String template = "Hello, %s!";\n    private final AtomicLong counter = new AtomicLong();\n\n\t@ApiOperation(value = "Show Greeting Message" )\n\t \/\/Diz ao Swagger que essa opera\u00e7\u00e3o REST deve ser documentado\n\t@ResponseStatus(HttpStatus.OK)\n    @RequestMapping(method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)\n    public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) {\n        return new Greeting(counter.incrementAndGet(), String.format(template, name));\n    }\n}\n<\/pre>\n
Como se pode ver \u00e9 extremamente simples documentar a nossa API<\/strong> agora vamos vazer o mesmo com o endpoint Person<\/strong>.<\/p>\n
\npackage br.com.erudio.web.controllers;\n\nimport java.util.List;\n\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.http.HttpStatus;\nimport org.springframework.http.MediaType;\nimport org.springframework.web.bind.annotation.PathVariable;\nimport org.springframework.web.bind.annotation.RequestBody;\nimport org.springframework.web.bind.annotation.RequestMapping;\nimport org.springframework.web.bind.annotation.RequestMethod;\nimport org.springframework.web.bind.annotation.ResponseStatus;\nimport org.springframework.web.bind.annotation.RestController;\n\nimport com.wordnik.swagger.annotations.Api;\nimport com.wordnik.swagger.annotations.ApiOperation;\n\nimport br.com.erudio.models.Person;\nimport br.com.erudio.services.PersonService;\n\n@Api(value = "person") \/\/Diz ao Swagger que esse \u00e9 um endpoint e REST deve ser documentado\n@RestController\n@RequestMapping("\/person\/")\npublic class PersonController {\n\n\t@Autowired\n\tprivate PersonService personService;\n\n\t@ApiOperation(value = "Find person by ID" )\n\t\/\/Diz ao Swagger que essa opera\u00e7\u00e3o REST deve ser documentado\n    @ResponseStatus(HttpStatus.OK)\n    @RequestMapping(value = "\/{personId}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)\n    public Person get(@PathVariable(value = "personId") String personId){\n        return personService.findById(personId);\n    }\n\n\t@ApiOperation(value = "Find all persons" )\n\t\/\/Diz ao Swagger que essa opera\u00e7\u00e3o REST deve ser documentado\n\t@ResponseStatus(HttpStatus.OK)\n\t@RequestMapping(value = "\/findAll", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)\n\tpublic List<person> findAll(){\n\t\treturn personService.findAll();\n\t}\n\n\t@ApiOperation(value = "Create a new person" )\n\t\/\/Diz ao Swagger que essa opera\u00e7\u00e3o REST deve ser documentado\n\t@ResponseStatus(HttpStatus.OK)\n\t@RequestMapping(method = RequestMethod.PUT, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)\n\tpublic Person create(@RequestBody Person person){\n\t\treturn personService.create(person);\n\t}\n\n\t@ApiOperation(value = "Update an existing person")\n\t\/\/Diz ao Swagger que essa opera\u00e7\u00e3o REST deve ser documentado\n\t@ResponseStatus(HttpStatus.OK)\n\t@RequestMapping(method = RequestMethod.POST,consumes = MediaType.APPLICATION_JSON_VALUE)\n\tpublic Person update(@RequestBody Person person){\n\t\treturn personService.update(person);\n\t}\n\n\t@ApiOperation(value = "Delete person by ID" )\n\t\/\/Diz ao Swagger que essa opera\u00e7\u00e3o REST deve ser documentado\n\t@ResponseStatus(HttpStatus.OK)\n    @RequestMapping(value = "\/{personId}", method = RequestMethod.DELETE)\n    public void delete(@PathVariable(value = "personId") String personId){\n        personService.delete(personId);\n    }\n}\n<\/pre>\n
N\u00e3o parece mas j\u00e1 terminamos toda a codifica\u00e7\u00e3o necess\u00e1ria por adicionar o Swagger<\/strong> \u00e0 nossa API<\/strong> mais uma vez acesse a classe Application<\/strong> e inicie a aplica\u00e7\u00e3o como no post anterior. Ap\u00f3s inicializada a aplica\u00e7\u00e3o acesse a URL:<\/p>\n
\n\tlocalhost:8080\/sdoc.jsp\n<\/pre>\n
Essa \u00e9 a URL padr\u00e3o da documenta\u00e7\u00e3o e nunca tentei alter\u00e1-la. Ao acess\u00e1-la voc\u00ea ver\u00e1 algo similar a imagem abaixo documentando cada uma das opera\u00e7\u00f5es dos nossos endpoints. Bastando clicar sobre cada uma para expandir e ver todos os detalhes da mesma.<\/p>\n
\"postagem_3_1\"<\/a><\/p>\n
Na imagem abaixo podemos ver a documenta\u00e7\u00e3o da opera\u00e7\u00e3o findAll<\/strong>. Temos a defini\u00e7\u00e3o do modelo que ela nos retorna, o tipo de dados que ela retorna no caso JSON<\/strong>, os StatusCode<\/strong> que ela pode retornar, se clicarmos em Try Out<\/strong> o Swagger<\/strong> nos permite testar nossas opera\u00e7\u00f5es. Ao executarmos esse teste a nossa API<\/strong> nos retornou um array de pessoas, o cabe\u00e7alho e o StatusCode 200 OK<\/strong>.<\/p>\n
\"postagem_3_5\"<\/a><\/p>\n
Chegamos com este post ao final da s\u00e9rie de posts, pr\u00e1ticos, sobre servi\u00e7os REST<\/strong>. Voc\u00ea pode baixar o c\u00f3digo deste post aqui<\/a> e descompactar o arquivo zip e importar na sua IDE preferida ou clonar usando Git:<\/p>\n
\ngit clone https:\/\/github.com\/leandrocgsi\/simple-rest-example-swagger.git\n<\/pre>\n
Agora voc\u00ea j\u00e1 consegue dar os primeiros passos na cria\u00e7\u00e3o de servi\u00e7os REST<\/strong>, conhece conceitos, te\u00f3ricos e pr\u00e1ticos, b\u00e1sicos para executar esse tipo de tarefa. Sendo assim continue ligado no blog, por que no pr\u00f3ximos posts iremos detonar o Rock’n Roll com outras tecnologias. \u00c9 isso a\u00ed bons estudos.<\/p>\n
Treinamentos relacionados com este post<\/h2>\n
<\/p>\n

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

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

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

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

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

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

\n        
\n<\/a><\/p>\n<\/person>\n","protected":false},"excerpt":{"rendered":"
O Swagger \u00e9 um dos frameworks mais usados para se documentar API’s REST. Ele facilita para que os clientes que consomem nossas API’s saibam quais os par\u00e2metros nossas opera\u00e7\u00f5es recebem, qual o retorno, o modelo, o media type retornado JSON, XML, CSV, bin\u00e1rio etc. Sendo assim os clientes n\u00e3o precisam necessariamente discutir com a equipe […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[57,96,103,104,105,115],"tags":[132,184,221,230,231,240],"_links":{"self":[{"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/posts\/753"}],"collection":[{"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/comments?post=753"}],"version-history":[{"count":3,"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/posts\/753\/revisions"}],"predecessor-version":[{"id":1512,"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/posts\/753\/revisions\/1512"}],"wp:attachment":[{"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/media?parent=753"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/categories?post=753"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.erudio.com.br\/blog\/wp-json\/wp\/v2\/tags?post=753"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}