Java Spring Boot Swagger API Dökümantasyonu

Published in

alBarakaTech Global

4 min readNov 2, 2020

Birden fazla ekip ve yazılımcının çalıştığım projelerde yazılan kodun dökümantasyonu çok önemlidir. Özellikle client çeşitliliğinin (mobile, web, IoT, Tv, v.s.) bir hayli fazla olduğunu düşünecek olursak projelerde mutlak gereklilik haline gelmiştir.

API projelerinde birden fazla endpoint bulunmaktadır. Her bir endpoint hangi parametreler ile çalıştığı ve hangi response’ları döndüğünün takibi, dökümantasyon yapmadan takip edilmesi çok riskli ve zordur.

Bu noktada API projelerimizde bize kolaylık sağlayacak olan Swagger bir çok dilde destek sunmaktadır.

Ayrıca Swagger’ın çözüm sağladığı diğer konular şöyledir;

API Design
API Development
API Testing
API Mocking and Virtualization
API Governance
API Monitoring

Bu yazımızda java ile swagger entegrasyonuna göz atarak API dökümantasyon konusunu irdeleyeceğiz.

Öncelikle https://start.spring.io/ adresine girerek yeni bit spring boot projesi oluşturalım. (com.swaggerdemo.post) Projemize bağımlılık olarak Spring Web’i dahil edelim.

Pom.xml içine bağımlılıklarımızı ekleyelim.

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.8.0</version>
   <scope>compile</scope>
</dependency><dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.8.0</version>
   <scope>compile</scope>
</dependency><dependency>
   <groupId>javax.xml.bind</groupId>
   <artifactId>jaxb-api</artifactId>
   <version>2.3.0</version>
</dependency>

Projemizde com.swaggerdemo.post package içine bir tane DTO tanımlayalım.

Post Class:

public class Post {
    public Long id;
    public String Title;
    public String BodyText;

    public Long getId() {
        return id;
    }

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

    public String getTitle() {
        return Title;
    }

    public void setTitle(String title) {
        Title = title;
    }

    public String getBodyText() {
        return BodyText;
    }

    public void setBodyText(String bodyText) {
        BodyText = bodyText;
    }
}

Yine aynı dizin PostController ekleyelim ve aşağıdaki gibi iki adet endpoint ekleyelim. Ayrıca init methodumuzun içinde örnek olarak data ekleyelim.

@RestController
@RequestMapping("/post")
public class PostController {

    private List<Post> postList = new ArrayList<Post>();

    @PostConstruct
    public void init() {
        postList.add(new Post( 1L, "Lorem Ipsum is simply dummy text", "Lorem Ipsum is simply dummy text of the printing and typesetting industry. "));
    }

    @GetMapping()
    public ResponseEntity<List<Post>> getPosts() {
        return ResponseEntity.ok(postList);
    }

    @PostMapping()
    public ResponseEntity<List<Post>> savePost(@RequestBody Post post) {
        postList.add(post);
        return ResponseEntity.ok(postList);
    }
}

Swagger’ı projemize dahil etmek için application void methodumuza aşağıdaki annotationı ekleyelim.

@SpringBootApplication
@EnableSwagger2
public class PostApplication {

   public static void main(String[] args) {
      SpringApplication.run(PostApplication.class, args);
   }

}

Ardından proje dizinine SwaggerConfig dosyası ekleyerek configleri yapalım.

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swaggerdemo.post"))
                .paths(regex("/.*"))
                .build()
                .apiInfo(metaData());
    }
    private ApiInfo metaData() {
        return new ApiInfoBuilder()
                .title("Spring Boot Swagger")
                .description("\"Spring Boot Swagger Demo Uygulaması\"")
                .version("1.0.0")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0\"")
                .contact(new Contact("Abdulkerim Karaman", "github.com/akaramanapp", "abdulkerimkaraman@gmail.com"))
                .build();
    }
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

Burada dikkat edilmesi gereken hususlar. BasePackage kısmında dökümante edilecek proje package dizinini belirterek api version bilgisini girebilirsiniz. Ayrıca addResourceHandlers methodunu override ederek swagger’a ulaşacağımız UI ekranının index html’ini tanımlıyoruz.

Config dosyamızı tanımladıktan sonra annotation’ larımızı kullanmaya başlayabiliriz.

Öncelikle post DTO nesnemizde değişikliklerimiz yapalım.

@ApiModel(value ="Post DTO", description ="Post Data Transfer Object")
public class Post {

    public Post(Long id, String title, String bodyText) {
        this.id = id;
        title = title;
        bodyText = bodyText;
    }

    @ApiModelProperty(value="Post dto Id alanı.", required = true)
    public Long id;

    @ApiModelProperty(value="Post dto title alanı.", required = true)
    public String title;

    @ApiModelProperty(value="Post dto bodytextalanı.", required = true)
    public String bodyText;

    public Long getId() {
        return id;
    }

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

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getBodyText() {
        return bodyText;
    }

    public void setBodyText(String bodyText) {
        this.bodyText = bodyText;
    }
}

Model dosyamızda kullandığımız swagger annotation’ ları şu şekildedir.

ApiModel içine sadece value bilgisi geçerek dto muz hakkında açıklama ekledik.

ApiModelProperty için value ve zorunlu alan olduğunu belirttik.

PostController class’ımızda ise aşağıdaki tanımlamalarımızı yapalım.

@RestController
@RequestMapping("/post")
@Api(value = "Post API Dökümantasyonu")
public class PostController {

    private List<Post> postList = new ArrayList<Post>();

    @PostConstruct
    public void init() {
        postList.add(new Post( 1L, "Lorem Ipsum is simply dummy text", "Lorem Ipsum is simply dummy text of the printing and typesetting industry. "));
    }

    @GetMapping()
    @ApiOperation(value="Post listesi döner")
    public ResponseEntity<List<Post>> getPosts() {
        return ResponseEntity.ok(postList);
    }

    @PostMapping()
    @ApiOperation(value="Post ekler.")
    public ResponseEntity<List<Post>> savePost(@RequestBody @ApiParam("Post parametresi") Post post) {
        postList.add(post);
        return ResponseEntity.ok(postList);
    }
}