Swagger로 rest api 문서화 하기

지난 번에 구현했던 rest api 프로젝트에 Swagger를 통해서 문서화 하고 rest api를 테스트 해 볼 수 있는 web ui를 만드는 방법을 소개합니다.

스웨거는 rest api를 문서화 하고 기술하는 스펙임. swagger.json 혹은 swagger.yaml이 곧 rest api의 명세를 작성하는 방법이 되는 것. 서브 프로젝트로

• swagger-editor : 스웨거 명세를 작성하게 도와주는 텍스트 에디터. 온라인 데모
• swagger-ui: swagger api를 문서화 해서 보여주고 직접 rest api call도 해볼 수 있음 온라인 데모
• swagger-codegen : swagger 명세를 기반으로 각 언어로 소스 뼈대를 만들어줌. Java, Scala, node 등을 지원해 줌.
  등이 있고, 잘 사용하면 유용하게 사용할 수 있다.

swagger integration

먼저 pom.xml 에 swagger dependency를 추가하고

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jersey2-jaxrs</artifactId>
    <version>1.5.0</version>
</dependency>

web.xml. Jersey2Config는 swagger.json을 위한 것이고 기타 api.version과 basepath등을 여기서 설정해 준다.

<servlet>
    <servlet-name>jersey</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>jersey.config.server.provider.packages</param-name>
        <param-value>
            io.swagger.jaxrs.listing,
            com.nberserk.rest
        </param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet>
    <servlet-name>Jersey2Config</servlet-name>
    <servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
    <init-param>
        <param-name>api.version</param-name>
        <param-value>1.0.0</param-value>
    </init-param>
    <init-param>
        <param-name>swagger.api.basepath</param-name>
        <param-value>http://localhost:8080/rest</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>

Swagger로 annotation추가 하기

이제 문서화를 할 차례다. Hello class에는 @Api, @ApiOperation annotation으로 Model class에는 @ApiModel, @ApiModelProperty로 annotation을 달아주면 나중에 swagger-ui로 보면 어노테이션한 설명들이 표시가 된다.

annotation된 Hello class

@Api(value="/hello", description="hello APIs")
@Path("hello")
public class Hello {

    static Model model;
    static {
        model = new Model("Darren");
        model.setDesc("description");
    }

    @ApiOperation(value = "", notes = "Gets model (text)", response = Model.class)
    @Path("/text")
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String getText(){
        return model.toString();
    }

    @ApiOperation(value = "", notes = "Gets model (json)", response = Model.class)
    @Path("/json")
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Response getJson() {
        return Response.ok().entity(model).build();
    }

    @ApiOperation(value = "", notes = "Gets model (xml)", response = Model.class)
    @Path("/xml")
    @GET
    @Produces(MediaType.APPLICATION_XML)
    public Response getXml(){
        return Response.ok().entity(model).build();
    }
}

annotation된 Model class

ApiModel(description="Model")
@XmlRootElement
public class Model {
    String id;
    String desc;

    public Model(String id){
        this.id = id;
    }

    @ApiModelProperty(required = true, value = "id")
    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public void setDesc(String desc) {
        this.desc = desc;
    }

    @ApiModelProperty(value = "description")
    public String getDesc() {
        return desc;
    }

    @Override
    public String toString() {
        return "id: " + id + ", desc: " + desc;
    }
}

Swagger가 잘 설정되었는지를 보려면 브라우저로 rest/swagger.json 여기 들어가서 json 파일이 보면 설정이 잘 된 것이다.

swagger-ui

자 이제 모든 준비는 끝났다. swagger-ui에 가서 http://localhost:8080/rest/swagger.json을 입력하면 annotation에서 기술했던 정보들이 문서화 되어서 나오고, 여기서 바로 rest api를 불러 볼 수 도 있다. 모든 개발자는 문서화를 싫어하고, 소스와 싱크를 맞추는 일 또한 노력과 정성이 들어가기 때문에 소스에 annotation만 잘 해주면 싱크도 맞춰지니까 유용한 툴이 될 것이다. 아래 스크린샷 참고.

Reference

실제로 동작하는 프로젝트는 github에 공유되어 있으니 참고하시면 되겠다.

revision history

• 2015/7/14 initial draft
• 2015/7/17 rest/swagger 분리