Integrating Swagger into a Spring Boot RESTful Webservice with Springfox

Spring Boot 와 Swagger를 연동하는 프로젝트 입니다.

아래 정리 해 놓은 것을 번역해서 정리 해 봤습니다. 

차근차근 따라하면 어려운 것은 없었습니다만.... springfox 레퍼런스는 다시 정리를 해야 하는 상황이네요 ;;;

아직 허락은 안받고, 그냥 번역 해서, 제가 코딩하면서 캡쳐한 화면만 올려 놨습니다. 

어색한 부분은 직접 가서 영문을 확인해 보시는 것이 가장 도움이 많이 될것 같습니다.

http://www.hascode.com/2015/07/integrating-swagger-into-a-spring-boot-restful-webservice-with-springfox/

Spring Boot는 RESTful web-service를 쉽게 생성하도록 해주고,

Swagger는 그 능력과 이 서비스들의 동작들을 설명하기 위한 형태로 명시하고,

Swagger UI와 함께 브라우저상에서 멋진 그래픽 유저 인터페이스를 가지고 REST API를 탐색하는 것이 가능하도록 한다.

Springfox는 Spring으로 구축한 API를 위해 자동으로 생성되는 JSON API 문서를 겨냥한 프로젝트 이며,

간단한 어플리케이션안에 Swagger를 통합하기 위한 아래 튜토리얼상에서 사용되어진다. 

Contents 1. Creating our RESTful WebService with Spring Boot      1. Gradle Configuration      2. DateFormat Value Object      3. Resource Controller      4. Spring Application Container      5. Directory Structure 2. Exploring the Application      1. Starting with Gradle      2. Calling the RESTful Webservice      3. Swagger Definition Export      4. Swagger UI 3. Swagger for JAX-RS based Webservices 4. Testing RESTful Webservices 5. Additional REST articles of mine 6. Tutorial Sources 7. Resources 8. Article Updates

1. Creating our RESTful WebService with Spring Boot

당장!!! Spring Boot를 이용해서 RESTful 웹서비스를 셋업합시다.

우리의 RESTful 웹서비스는 유저에게 현재 날짜를 JSON 구문으로 커스터마이징 포멧을 리턴하는 것입니다.

추가적으로 증가된 카운터도 리턴합니다.

예제 : 사용자가 yyyy 포멧을 기입하면, 우리 웹서비스는 현재 년도를 4 자리로 리턴합니다. e.g. 2015

Spring Boot로 웹서비스를 만드는 것에 대한 상세 내용에 대해서는 

아래 링크에 있는 멋진 튜토리얼을 읽어보는 것을 강력하게 추천한다.

"Building a RESTful Webservice" : https://spring.io/guides/gs/rest-service/

     1. Gradle Configuration

          

          아래는 build.gradle 소스 입니다.  근데 , 나는 Maven으로 하고 싶단 말이죠.

          

          그럼 미친척 하고, 저는 Maven으로 세팅을 해보도록 하겠습니다.

          project 이름은 : dateconv-rect-serivce

          default package :  com.hascode.tutorial

          

          틀릴수도 있겠지만, starter-web 과 spring-fox-swagger2 , springfox-swagger-ui 이건 모두 2.2.2 최신으로 변경하고,

          마지막으로 junit은 start-test로 마무리 했다.

     2. DateFormat Value Object

          

          이 POJO는 date , counter 그리고 유저의 데이터 패턴으로 포멧된 것을 캡슐화 했다.

          생성자와 getter만 생성을 했습니다. 

          

     3. Resource Controller

         이 컨트롤러는  엔트리 포인트 URL 패턴 , pattern은 원하는 날짜 포멧을 기입하기 위한 path 파라미터를 표기하는 곳인,
         "/currentdate/{pattern}"로 RESTful 웹서비스을 정의한다.

          마지막으로 컨트롤러는 생성하고 새로운 값 객체를 포멧된 date를 가지고 리턴합니다.

          

          * 이중에서 AtomicLong 은 잘 안쓰는 건데..  간단히 설명하면, 

     4. Spring Application Container

          

          RESTful 웹서비스를 동작시킬 때 필요한 모든 건 바로 main 메소드이고,  우리 어플리케이션에 쓰일 swagger를 셋업하는데 또 다른 설정이 사용된다.

          우리가 Springfox를 사용하는데 추가적인 코드는 ...

          - enable Springforx Swagger 2 

          - Spring API 컨트롤러들이 위치를 명시

          - 새로운 Docket(Docket은 Springfox 프라이머리 설정 매카니즘이다.) 셋업

          - 경로들(Paths) 셋업, security , API Tokens 그리고 기타 등등.

          복사 그리고 붙이기를 원치 않기 때문에, 나는 모든것과 디테일한 것까지 매우 잘 설명되어 있는 Springfox reference 문서를 보는 것을 강력히 추천한다.

          http://springfox.github.io/springfox/docs/current/  ==> 번역해야 겠네;;

          

          

     5. Directory Structure

          프로젝트 구조는 아래와 같이 보여야 한다고 합니다. 

          

2. Exploring the Application

     자 이제 탐색을 할 시간이 되었답니다.

     1. Starting with Gradle

          Gradle를 사용해서, 어플리케이션이 부트시켜 봅시다. 저는... 메이븐입니다요.

          

     2. Calling the RESTful Webservice

          우선 우리 RESTful 웹 서비스 사용해봅시다.

          http://localhost:8080/currentdate/PATTERN  

          PATTERN 에는 유효한 데이터 포멧을 넣으면 됩니다. (http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html)

          e.g. http://localhost:8080/currentdate/yyyy , http://localhost:8080/currentdate/yyyy-MM-dd

          

     3. Swagger Definition Export

          Swaggger는  즉시 우리 서비스들을 위해  REST 클라이언트를 생성하기 위해 사용되어질 우리를 위해 완벽한 서비스 문서를 생성합니다. 

          (e.g. Swagger Editor 와 같이 온라인 에디터를 사용 , http://editor.swagger.io/#/) 

          우리는 http://localhost:8080/v2/api-docs   에서 JSON 포멧으로 문서에 접근 할 수 있습니다. 

          

          

          서비스 문서에서 발취한 것입니다. 

     4. Swagger UI

          

          Swagger UI는 우리 REST API를 탐색이 가능하게 하고 서비스들을 가지고 동작하도록 합니다.

          http://localhost:8080/swagger-ui.html

          

3. Swagger for JAX-RS based Webservices

     

    " Documenting RESTFul Webservices in Swagger, AsciiDoc and Plan Text with Maven and the JAX-RS Analyzer" 

     http://www.hascode.com/2015/06/documenting-restful-webservices-in-swagger-asciidoc-and-plain-text-with-maven-and-the-jax-rs-analyzer/

    이 시나리오를 위해 제발 부담없이 위에 블로그 기사를 봐주세요 .

4. Testing RESTful Webservices

     제발!!! 나의 아래 블로그 기사를 봐주세요. 

     Testing RESTful Web Services made easy using the REST-assured Framework.

     http://www.hascode.com/2011/10/testing-restful-web-services-made-easy-using-the-rest-assured-framework/

     REST-assured vs Jersery-Test-Framework : Testing your RESTful Web-Services

     http://www.hascode.com/2011/09/rest-assured-vs-jersey-test-framework-testing-your-restful-web-services/

5. Additional REST articles of mine

     

     다른 관점에서 다루거나, 생성하는 RESTful 웹서비스들을 다루는 아래 튜토리얼들도 봐주세요.

     위에서 링크 걸어 놓은 것을 제외한 나머지 링크를 붙입니다.

     JAX-RS Server API Snippets

     http://www.hascode.com/2014/09/jax-rs-server-api-snippets/

     JAX-RS 2.0 REST Client Features by Example

     http://www.hascode.com/2013/12/jax-rs-2-0-rest-client-features-by-example/

     Creating a REST Client Step-by-Step using JAX-RS, JAX-RS and Jersey     

     http://www.hascode.com/2010/11/creating-a-rest-client-step-by-step-using-jax-rs-jax-b-and-jersey/

     Creating REST Clients for JAX-RS based Webservices with Netflix Feign

     http://www.hascode.com/2015/10/creating-rest-clients-for-jax-rs-based-webservices-with-netflix-feign/

6. Tutorial Sources

     위의 소스는 이 분의 Bitbucket repository에 넣어 놨다고 합니다. 

     

git clone https://bitbucket.org/hascode/springboot-swagger-springfox-tutorial.git

7. Resources

     - Spring Framework Website : https://spring.io/

     - Springfox on Github : https://github.com/springfox/springfox

     - Springfox Integration Tutorial : http://springfox.github.io/springfox/docs/current/

     - Spring Tutorial : Building a RESTful Webservice : https://spring.io/guides/gs/rest-service/

     - Swagger Website : http://swagger.io/

     - Creating REST Clients for JAX-RS based Webserives with Netflix Feign : http://www.hascode.com/2015/10/creating-rest-clients-for-jax-rs-based-webservices-with-netflix-feign/

8. Article Updates

     2015-08-06 : Links to other REST articles of mine added

     2015-10-22 : Link list updated