Swagger, REST API 문서자동화

2020. 12. 14. 21:19

REST API 문서 자동화를 간편하게 해주는 Swagger툴에 대해서 알아보자.

Swagger의 정의

swagger란 REST API를 관리하기 쉽도록 구현한 오픈소스이다.
개발을 하다 보면, 다른 개발자나 고객과의 필요한 것이 바로 API 명세이다.
개발자에게 문서 작업은 거의 업무의 절반일 정도로 상당하다.
게다가 언어 별로 각각 open api를 만들기는 쉽지 않다.
그래서 문서 및 테스트 자동화로 나온것이 swagger라고 할 수 있다. ( 나도 처음 써봐서 잘은 모르겠지만.. )

Swagger 활용 : swaggerhub

https://app.swaggerhub.com/home

swagger내에서도 swagger editor, swagger codezen, swagger ui 로 세분화 되어 서비스가 되고있는데
현재는 Swaggerhub로 전체 통합 됬으며, 특정 서비스 이상은 유료라는 단점이 있다. 필요에 따라 각각 다운로드 해서 사용할 수도 있다.

Swagger Editor ( API 문서 자동화 )

Swagger Editor는 Swagger spec에 따라 RESTful API를 설계, 정의 및 문서화하기 위한 오픈 소스 편집기다.
demo site : https://editor.swagger.io/
docker로도 설치 가능하다. > localhost:80 로 접속 editor 확인. json이나 yaml 파일로 작성 가능.

# docker로 swagger-editor 설치 명령어
 
docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

Swagger Codezen( open source 활용 및 sdk 생성 )

OpenAPI 명세에 따른 client library (SDK 생성), server stub 및 문서를 자동으로 생성 할 수 있도록 하는 오픈 소스 프로젝트다.
GitHub repository에서 다운로드하거나 통합 SwaggerHub 플랫폼에서 기존에 정의 된 OpenAPI 에 대해 생성 할 수 있다.

Swagger UI( API test )

명세된 api를 UI로 확인 할 수 있는 에디터다. 개발 시에 swagger를 적용하면, 자동적으로 생성된다.
Open api 리스트를 쉽게 확인 할 수 있고, 테스트도 바로 가능하다.
demo site : https://petstore.swagger.io/

Swagger 적용 및 실습 : springboot + gradle + swagger

먼저, 간단한 spring boot 프로젝트를 하나 만든다.
예시로 네이버 실시간 속보뉴스 ( 분야별 ) 현재 인기뉴스 ( 분야별 ) 을 구현했다.
git 에서 받아보자. 윤지 깃 주소 : 지금은 회사 비트버켓에 있자나…ㅠ 가지구와야해
swagger를 적용하기 위해서는 먼저 gradle에 의존성을 추가해주어야 한다. 현재는 3버전이 나왔는데, 일단 2.9버전을 사용해보았다. 3버전에서 달라진 것과 적용은 다음 codezen 실습 편에서 보자.

//swagger  
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

그리고, swagger config 를 작성 해야 한다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    private String version;
    private String title;
 
 
    //REST API의 경우는 보통 version 별로 관리한다.
    // Docket을 버전 별로 여러개 만들어서 테스트도 가능하다.
    @Bean
    public Docket apiV1() {
        version = "v1";
        title = "naver news crawling API " + version;
 
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false) // swagger 에서 기본적으로 제공하는 return 메세지를 사용하지 않는다는 의미. 따로 설정 가능
                .groupName(version) //Docket Bean이 두 개이상 일 경우 충돌 방지
                .select() //ApiSelectorBuilder를 생성
                .apis(RequestHandlerSelectors.basePackage("com.crawling.controller")) //api 스펙이 작성되어 있는 패키지를 지정 , 지정하지 않고 any로 설정 할 수도 있다.
                .paths(PathSelectors.ant("/v1/news/**")) // apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화
                .build()
                .apiInfo(apiInfo(title, version)); // api 정보 설정
 
    }
 
    // ApiInfo( title, description, version, termsOfServiceUrl, contact, license, licenseUrl, vendorExtensions )
    // 파라미터 설정
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfo(
                title,
                "Swagger로 생성한 네이버 뉴스 API Docs",
                version,
                "www.example.com",
                new Contact("Contact Me", "www.example.com", "yunjigo@gmail.com"),
                "Licenses yunji",
                "www.example.com",
                new ArrayList<>());
 
                 
    }
     
}

4.해당 요청을 처리할 controller에도 swagger와 관련된 설정을 해준다.

@RestController
@Api(value = "CrawlingController v1") // swagger api 설정 해준다.
@RequestMapping("/v1/news") // 특정 요청 값 mapping
public class CrawlingController {
     
    SimpleDateFormat sdf = new SimpleDateFormat("yyyyMMdd");
    
   @ApiOperation(value = "네이버 뉴스 속보 스크래핑", notes = "속보입니다.") // api 속성 값 설정
   @GetMapping(value="/break/{type}")
   public News getBreakNews( // api param 정보 설정, required true 일 경우 필수
             @ApiParam(value = "뉴스타입", required = true, example = "it") @PathVariable("type") String type)
             throws IOException {
 
        String date = sdf.format(Calendar.getInstance().getTime());
        //네이버 뉴스 속보 url
        String url ="https://news.naver.com/main/list.nhn?listType=title&mode=LSD&mid=sec&sid1="
                    + NewsEnum.valueOf(type).getCode() + "&date="+ date;
 
        Connection.Response response = Jsoup.connect(url)
                                        .userAgent("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36")
                                        .method(Method.GET)
                                        .execute();
 
          NewsInfo newsInfo = new NewsInfo();                             
          newsInfo.setDate(date);
          newsInfo.setUrl(url);
          newsInfo.setNewsType(NewsEnum.valueOf(type).getType());
          newsInfo.setDesc(NewsEnum.URL_BREAK.getType());              
 
          Document document = response.parse();
          // 파싱할 elements 들을 가져온다.
          // https://try.jsoup.org/ 홈페이지 참고하면 좋음
          Elements elements  =  document.select("div[class='list_body newsflash_body'] > ul > li").removeAttr("i");
          Elements urls = elements.select("a[href]");
 
          ArrayList<NewsDetail> newsDetails = new ArrayList<NewsDetail>();
          int cnt = 0;
          for(Element element : elements ){
               NewsDetail newsDetail = new NewsDetail();
               newsDetail.setUrl(urls.get(cnt++).attr("abs:href"));
               newsDetail.setTitle(element.text().replace("포토", ""));
               newsDetails.add(newsDetail);
          }
 
          News news = new News();
          news.setNewsInfo(newsInfo);
          news.setNewsDetails(newsDetails);
 
       return news;
   }
 
}

서버를 구동해서 localhost 로 요청을 해본다. ( 정상적으로 json 데이터가 나오는 것을 확인한다.)
참고로 spring boot 는 jackson library 가 default로 내장 되어있어 object를 return할 경우 json으로 자동 convert된다.
대신, object를 구현할 때 setter, getter 구현이 되어 있어야 한다.
http://localhost:8080/swagger-ui.html#/ 로 접속해서 구현한 api 문서를 확인해본다.
https://inspector.swagger.io/builder 로 이동한다.
여기서도 api test를 할 수 있다. 추가로 성능테스트도 가능한데, 유료버전이다.
여러개 api를 collection에 추가할 수 있고 해당 api를 토대로 위와 같은 문서를 만들 수도 있다.
collection을 만들고 create api definition 을 클릭한다.
연결된 swagger hub 계정으로 이동 되며,code zen을 확인 할 수 있다.
api를 알맞게 수정 가공해서 배포 가능하다.
https://swagger.io/docs/swagger-inspector/how-to-create-an-openapi-definition-using-swagger/

맛보기로 swagger를 실습했는데, 매우.. 편리한 기능인 것 같다. 왜 나는 진즉에 몰랐지..?
역시 정보력이 바로 기술력이구나..
무튼 이렇게 코드에 어노테이션 형식으로쓰면, 나중에 오히려 관리하기가 상당히 복잡할 수도 있다.
오늘은 뉴비니까 이렇게 했지만 다음엔 버전3으로 codezen을 이용하여 소스에서 각종 어노테이션을 제거해서 문서를 만들어 볼 것이다.( 진짜다. )

'IT정보 > IT정보' 카테고리의 다른 글

Open JDK, Oracle JDK 차이 (0)	2021.02.27

윤복로그