swagger 사용하기

# swagger 사용하기

-------------------------------------

0. swagger 소개

    - [web](http://swagger.io/)

    - Tools

    - SWAGGER UI: html 기반으로 API DOCS 및 TEST 지원

        - SWAGGER EDITOR: swagger yaml / json 형식의 파일 생성 / 수정 가능하며 바로 UI 표현식을 보여줌

        - SDK GENERATORS: swagger 파일을 통해 server-side / client 용 code 를 생성

1. swagger 를 통한 REST API docs 만들기

- maven 

- dependency 설정

<!-- https://mvnrepository.com/artifact/io.swagger/swagger-core -->      <dependency>                 <groupId>io.swagger</groupId>                 <artifactId>swagger-core</artifactId>                 <version>1.5.10</version>             </dependency>

- build 값 추가

<build>                 <plugins>                     ...                     <plugin>                         <groupId>com.github.kongchen</groupId>                         <artifactId>swagger-maven-plugin</artifactId>                         <version>1.1-SNAPSHOT</version>                         <configuration>                             <apiSources>                                 <apiSource>                                     <locations>com.foo.bar.apis;com.foo.bar.apis.internal.Resource</locations>                                     <apiVersion>v1</apiVersion>                                     <basePath>http://www.example.com</basePath>                                     <outputTemplate>strapdown.html.mustache</outputTemplate>                                     <outputPath>generated/strapdown.html</outputPath>                                     <withFormatSuffix>false</withFormatSuffix>                                     <swaggerDirectory>generated/apidocs</swaggerDirectory>                                 </apiSource>                             </apiSources>                         </configuration>                         <executions>                             <execution>                                 <phase>compile</phase>                                 <goals>                                     <goal>generate</goal>                                 </goals>                             </execution>                         </executions>                     </plugin>                     ...                 </plugins>             </build>

- Controller Class 에 swagger annotation 적용

- [annotation 소개](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X)

@Controller  @RequestMapping(value = "컨트롤러가 매핑되는 URL PATH", produces = {APPLICATION_JSON_VALUE})  @Api(value = "컨트롤러가 매핑되는 URL PATH", description = "controller 에 대한 설명을 써준다") // swagger annotation public class SampleAPIController { ...     @ApiOperation(  // swagger annotation value = "개별 API 에 대한 소개",  notes = "개별 API 에 대한 설명",  response = SampleResponseObject.class, responseContainer = "List"  )  @ApiResponses(  // swagger annotation value = {  @ApiResponse(code = 200, message = "Success Return Results"),  @ApiResponse(code = 0, message = "Unexpected error")  }  )  @RequestMapping(value = "/{pathVariable}", method = RequestMethod.GET)  public ResponseEntity<Collection<SampleResponseObject>> sendGetAPI( @ApiParam(value = "pathVariable 에 대한 설명", required = true)  @PathVariable String pathVariable,  @ApiParam(value = "파라미터에 대한 설명")  @RequestParam(value = "limits", required = false) Integer limits,  @ApiParam(value = "파라미터에 대한 설명") @RequestParam(value = "rollbackOptions", required = false) String rollbackOptions, @ApiParam(value = "Body 에 대한 설명", required = true) @RequestBody SampleRequestObject sRequestObject ) { ... } ... }

- maven build

- index.html

- ./json/*.yaml

2. swagger 를 통한 REST API SDK 만들기

- [web](http://editor.swagger.io/#/) 접속

- 1 에서 생성된 .yaml 파일을 왼쪽 탭에 입력

       

    - 상단 bar 의 Generate Clinet 선택

    - 다양한 language 를 지원 한다