<?xml version="1.0" encoding="UTF-8"?><rss version="2.0"
	xmlns:content="http://purl.org/rss/1.0/modules/content/"
	xmlns:wfw="http://wellformedweb.org/CommentAPI/"
	xmlns:dc="http://purl.org/dc/elements/1.1/"
	xmlns:atom="http://www.w3.org/2005/Atom"
	xmlns:sy="http://purl.org/rss/1.0/modules/syndication/"
	xmlns:slash="http://purl.org/rss/1.0/modules/slash/"
	>

<channel>
	<title>spring boot &#8211; Oscar Blancarte &#8211; Software Architecture</title>
	<atom:link href="https://www.oscarblancarteblog.com/category/spring-boot/feed/" rel="self" type="application/rss+xml" />
	<link>https://www.oscarblancarteblog.com</link>
	<description>Software Architect &#38; FullStack developer</description>
	<lastBuildDate>Fri, 28 Aug 2020 20:24:09 +0000</lastBuildDate>
	<language>es</language>
	<sy:updatePeriod>
	hourly	</sy:updatePeriod>
	<sy:updateFrequency>
	1	</sy:updateFrequency>
	<generator>https://wordpress.org/?v=7.1.4</generator>

<image>
	<url>https://www.oscarblancarteblog.com/wp-content/uploads/2019/03/cropped-ob-32x32.png</url>
	<title>spring boot &#8211; Oscar Blancarte &#8211; Software Architecture</title>
	<link>https://www.oscarblancarteblog.com</link>
	<width>32</width>
	<height>32</height>
</image> 
<site xmlns="com-wordpress:feed-additions:1">89905023</site>	<item>
		<title>Documentar un API REST con Swagger y Spring Boot</title>
		<link>https://www.oscarblancarteblog.com/2020/08/28/documentar-un-api-rest-con-swagger-y-spring-boot/</link>
					<comments>https://www.oscarblancarteblog.com/2020/08/28/documentar-un-api-rest-con-swagger-y-spring-boot/#comments</comments>
		
		<dc:creator><![CDATA[oblancarte]]></dc:creator>
		<pubDate>Fri, 28 Aug 2020 20:24:03 +0000</pubDate>
				<category><![CDATA[spring boot]]></category>
		<guid isPermaLink="false">https://www.oscarblancarteblog.com/?p=3262</guid>

					<description><![CDATA[Swagger nos permite auto documentar nuestra API REST sin necesidad de programar nada, ya que aprovecha las anotaciones de Spring Boot]]></description>
										<content:encoded><![CDATA[
<figure class="wp-block-image size-large"><img fetchpriority="high" decoding="async" width="852" height="477" src="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/swagger-banner.jpg" alt="" class="wp-image-3270" srcset="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/swagger-banner.jpg 852w, https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/swagger-banner-300x168.jpg 300w, https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/swagger-banner-768x430.jpg 768w" sizes="(max-width: 852px) 100vw, 852px" /></figure>



<p class="wp-block-paragraph">La documentación de un API es casi tan importante como construirlos con buenas prácticas, pues su finalidad es que terceros la utilicen, por tal motivo, documentarla correctamente puede representar el éxito o fracaso en su implementación dentro de los sistemas de terceros:</p>



<span id="more-3262"></span>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Codigo fuente: Antes que nada, puedes descargar todo el código fuente en: <a href="https://github.com/codminddev/blog-spring-boot-swagger">https://github.com/codminddev/blog-spring-boot-swagger</a></p></blockquote>



<p class="wp-block-paragraph">La documentación de un API es casi tan importante como construirlos con buenas prácticas, pues su finalidad es que terceros la utilicen, por tal motivo, documentarla correctamente puede representar el éxito o fracaso en su implementación dentro de los sistemas de terceros:</p>



<p class="wp-block-paragraph">Por suerte, Spring Boot cuenta con la librería de Swagger que permite analizar todo el proyecto y auto documentar todos los servicios REST que encuentre de forma automática. De esta forma, nos ahorramos una gran cantidad de trabajo de documentación. Por ejemplo, veamos el siguiente servicio:</p>



<pre title="UserController.java" class="wp-block-code"><code lang="java" class="language-java line-numbers">@RestController
public class UserController {
	
	private List&lt;UserDTO> users = new ArrayList&lt;>();
	
	public UserController() {
		users.add(new UserDTO(1L, "admin"));
		users.add(new UserDTO(2L, "supervisor"));
		users.add(new UserDTO(3L, "cajero"));
	}

	@GetMapping(value = "users")
	public ResponseEntity&lt;List&lt;UserDTO>> findAll(){
		return ResponseEntity.ok(users); 
	}
	
	
	@PutMapping(value = "users")
	public ResponseEntity&lt;UserDTO> update(UserDTO request){
		UserDTO user = users.stream()
				.filter(currentUser -> currentUser.getId() == request.getId())
				.findFirst()
				.orElseThrow(() -> new RuntimeException("No existe el usuario"));
		user.setName(request.getName());
		return ResponseEntity.ok(user);
	}
	
	@PostMapping(value = "users")
	public ResponseEntity&lt;UserDTO> create(UserDTO request){
		users.add(request);
		return ResponseEntity.ok(request);
	}
	
	@DeleteMapping(value = "users/{userId}")
	public ResponseEntity&lt;?> delete( @PathVariable("userId") long userId ) {
		UserDTO user = users.stream()
		.filter(currentUser -> currentUser.getId() == userId)
		.findFirst()
		.orElseThrow(() -> new RuntimeException("No existe el usuario"));
		users.remove(user);
		return ResponseEntity.ok().build();
		
	}
}</code></pre>



<p class="wp-block-paragraph">Podrá observar el clásico servicio CRUD de usuarios, donde tenemos un servicio para consultar todos los usuarios (GET), crear nuevos (POST), actualizarlos (PUT) y finalmente eliminarlos (DELETE).</p>



<p class="wp-block-paragraph">Por suerte, Swagger es tan potente que puede aprovecharse del API de reflection para analizar la estructura de los métodos, sus anotaciones y los parámetros de entrada y salida para auto documentar el API, tal como se puede ver en la siguiente imagen:</p>



<figure class="wp-block-image size-large"><img decoding="async" width="589" height="245" src="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image.png" alt="" class="wp-image-3263" srcset="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image.png 589w, https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-300x125.png 300w" sizes="(max-width: 589px) 100vw, 589px" /></figure>



<h2 class="wp-block-heading">Instalación</h2>



<p class="wp-block-paragraph">Para lograr esto, es requerido solamente dos pasos, agregar las librerías de Swagger y crear un objeto de configuración llamado <code>Docket</code>, veamos cómo sería:</p>



<p class="wp-block-paragraph">Lo primero es agregar las siguientes librerías en el archivo <code>pom.xml</code>:</p>



<pre title="pom.xml" class="wp-block-code"><code lang="xml" class="language-xml">&lt;dependency>
	&lt;groupId>io.springfox&lt;/groupId>
	&lt;artifactId>springfox-swagger2&lt;/artifactId>
	&lt;version>2.9.2&lt;/version>
&lt;/dependency>

&lt;dependency>
	&lt;groupId>io.springfox&lt;/groupId>
	&lt;artifactId>springfox-swagger-ui&lt;/artifactId>
	&lt;version>2.9.2&lt;/version>
&lt;/dependency></code></pre>



<p class="wp-block-paragraph">La primera (<code>springfox-swagger2</code>) es la más importante, pues es que se encarga de analizar la estructura de nuestro proyecto y crear los metadatos para crear la auto documentación del API. La segunda (<code>springfox-swagger-ui</code>) es que se encarga de tomar los metadatos de la primera y crear una interfaz gráfica amigable con los usuarios.</p>



<h2 class="wp-block-heading">Configuración</h2>



<p class="wp-block-paragraph">El segundo paso es crear el archivo <code>Docket</code>, mediante el cual le indicamos a Swagger que es lo que debe de tomar en cuanta al momento de crear la documentación. Para esto, debemos de crear una clase que este anotada con <code>@Configuration</code> y <code>@EnableSwagger2</code> y tenga un método que cree el objeto <code>Docket</code>:</p>



<pre title="SwaggerConfig.java" class="wp-block-code"><code lang="java" class="language-java line-numbers">@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket apiDocket() {
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.codmind.swaggerapi.controllers"))
				.paths(PathSelectors.any())
				.build()
				.apiInfo(getApiInfo())
				;
	}
	
	private ApiInfo getApiInfo() {
		return new ApiInfo(
				"Order Service API",
				"Order Service API Description",
				"1.0",
				"http://codmind.com/terms",
				new Contact("Codmind", "https://codmind.com", "apis@codmind.com"),
				"LICENSE",
				"LICENSE URL",
				Collections.emptyList()
				);
	}
}</code></pre>



<p class="wp-block-paragraph">Dentro del método <code>apiDocket</code> construimos el objeto <code>Docket</code>, en el cual le indicamos que tome todos los servicios que se encuentre en el paquete <code>com.codmind.swaggerapi.controllers</code> y los auto documente por nosotros.</p>



<p class="wp-block-paragraph">Finalmente, en el método <code>getApiInfo</code>, creamos el objeto <code>ApiInfo</code>, el cual define los datos de la propiedad del API, como su nombre, correo de contacto, licencia, etc.</p>



<h2 class="wp-block-heading">La ejecución</h2>



<p class="wp-block-paragraph">Si todo salió bien y corremos la aplicación, veremos el siguiente log:</p>



<figure class="wp-block-image size-full"><img decoding="async" width="589" height="181" src="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-1.png" alt="" class="wp-image-3264" srcset="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-1.png 589w, https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-1-300x92.png 300w" sizes="(max-width: 589px) 100vw, 589px" /></figure>



<p class="wp-block-paragraph">Podrás ver que nos ha generado un path llamado <em><strong>/v2/api-docs</strong></em>, por lo que si los accedemos en el navegador (<a href="http://localhost:8080/v2/api-docs">http://localhost:8080/v2/api-docs</a>) podremos ver los metadatos del API generado por la librería <code>springfox-swagger2</code>:</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="384" height="312" src="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-2.png" alt="" class="wp-image-3265" srcset="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-2.png 384w, https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-2-300x244.png 300w" sizes="auto, (max-width: 384px) 100vw, 384px" /></figure>



<p class="wp-block-paragraph">Sin embargo, esta documentación no es para nada intuitiva, y es por ello que hemos instalado la librería springfox-swagger-ui, la cual toma esta metadata y crea la URL: <a href="http://localhost:8080/swagger-ui.html">http://localhost:8080/swagger-ui.html</a>, la cual se ve así:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="589" height="489" src="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-3.png" alt="" class="wp-image-3266" srcset="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-3.png 589w, https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-3-300x249.png 300w" sizes="auto, (max-width: 589px) 100vw, 589px" /></figure>



<p class="wp-block-paragraph">En esta página podemos apreciar 3 secciones, la primera corresponde al objeto <code>ApiInfo</code>, que contiene nombre del API, licencia, datos de contacto, etc.</p>



<p class="wp-block-paragraph">La segunda sección corresponde a los servicios, agrupados por controlador. En este caso, podemos apreciar el <code>UserController</code> (user-controller) con las 4 operaciones CRUD que hemos definido.</p>



<div style="height:100px" aria-hidden="true" class="wp-block-spacer"></div>



<figure class="wp-block-image size-large"><a href="https://codmind.com/courses/api-rest-con-spring-boot" target="_blank" rel="noopener noreferrer"><img loading="lazy" decoding="async" width="800" height="450" src="https://www.oscarblancarteblog.com/wp-content/uploads/2019/08/banner-lg.jpg" alt="" class="wp-image-3146" srcset="https://www.oscarblancarteblog.com/wp-content/uploads/2019/08/banner-lg.jpg 800w, https://www.oscarblancarteblog.com/wp-content/uploads/2019/08/banner-lg-300x169.jpg 300w, https://www.oscarblancarteblog.com/wp-content/uploads/2019/08/banner-lg-768x432.jpg 768w" sizes="auto, (max-width: 800px) 100vw, 800px" /></a><figcaption>Si quieres aprender a crear un API REST profesional con Swagger, te invito a mi curso Mastering API REST, donde aprenderemos las mejores prácticas para crear un API REST.</figcaption></figure>



<div style="height:95px" aria-hidden="true" class="wp-block-spacer"></div>



<p class="wp-block-paragraph">Finalmente, tenemos la sección de Models (modelos), la cual describe todos los objetos que utilizamos como request/response.</p>



<h2 class="wp-block-heading">Probando el API</h2>



<p class="wp-block-paragraph">Finalmente, si expandimos cualquier servicio, por ejemplo, el método create (POST) y presionamos el botón Try It Out, podremos probar el servicio allí mismo:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="589" height="200" src="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-4.png" alt="" class="wp-image-3267" srcset="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-4.png 589w, https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-4-300x102.png 300w" sizes="auto, (max-width: 589px) 100vw, 589px" /></figure>



<p class="wp-block-paragraph">Nos desplegará los campos esperados por el servicio y si damos click en la sección Model, podrás ver la estructura de la respuesta esperada.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="589" height="329" src="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-5.png" alt="" class="wp-image-3268" srcset="https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-5.png 589w, https://www.oscarblancarteblog.com/wp-content/uploads/2020/08/image-5-300x168.png 300w" sizes="auto, (max-width: 589px) 100vw, 589px" /></figure>



<h2 class="wp-block-heading">Conclusiones</h2>



<p class="wp-block-paragraph">Documentar solo este servicio, nos podría tomar varias horas, ya que es necesario documentar su nombre, los parámetros que recibe, los retorna y además, habría que describir cada unos de los objetos que recibe y responde, para que los consumidores tengan claridad de la estructura de cada uno de estos, pero como hemos podido comprobar, mediante Swagger nos evitamos todo este trabajo.</p>
]]></content:encoded>
					
					<wfw:commentRss>https://www.oscarblancarteblog.com/2020/08/28/documentar-un-api-rest-con-swagger-y-spring-boot/feed/</wfw:commentRss>
			<slash:comments>27</slash:comments>
		
		
		<post-id xmlns="com-wordpress:feed-additions:1">3262</post-id>	</item>
	</channel>
</rss>
