Spring Boot Rest API Uygulama Swagger API Dökümantasyon Kullanım Örneği

Spring Boot Dersleri‘ne devam ediyoruz.

Bu dersimizde Spring Boot ile yaptığımız Rest uygulamalarımızın API Dökümante etmek ve yönetmek için kullanılan Swagger ile bu uygulamamıza entegre edip kullanımına bakacağız. Api dökümanlarımızı word dosyası yerine projemize gömülü ve dinamik olarak değişebilen bir dökümantasyon aracıdır.

Spring Boot projesi oluşturalım.

Projemizde Swagger kullanmak için eklememiz gereken bağımlılıklarımız ise şunlar;

<dependency>
   <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
</dependency>
Code language: HTML, XML (xml)

Projemizde Swagger’i kullanabilmemiz için Swagger konfigürasyonu yapmamız gerekmektedir. Konfigürasyon dosyamızı yazalım ve inceleyelim.

@EnableSwagger2
@Configuration
public class SwaggerConfiguration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.burakkutbay.swaggerspringboot"))
                .paths(PathSelectors.regex("/api.*"))
                .build()
                .apiInfo(info());
    }

    private ApiInfo info() {

        return new ApiInfo(
                "Student API",
                "Students API Description",
                "v1",
                "apiserviceurl",
                new Contact("Burak KUTBAY", "https://burakkutbay.com", "mail@adresi.com"),
                "MIT License",
                "https://opensource.org/licenses/MIT"
        );
    }
}
Code language: PHP (php)

@EnableSwagger2

Projemizde kullanabilmek için bu anotasyonu kullanıyoruz.

Docket

api adında bir method oluşturduk ve bu method Docket tipindedir. Docket sayesinde bir dökümantasyon oluşturulmasını ve Swagger2 tipinde olacağını belirttik. Ayrıca kullanılan rest api yolunu belirtiyoruz.

ApiInfo

ApiInfo ile ise dökümantasyonun başlığı, açıklaması, lisans türü, geliştirici iletişim bilgilerini tanımlıyoruz.

Basit bir model oluşturalım bu modelimizde Öğrenci bilgilerini içerecek. Student.java olacak.

public class Student {
    @ApiModelProperty(notes = "The database generated Stdudent ID")
    private int id;
    @ApiModelProperty(notes = "The database generated Stdudent Number")
    private long stdnumber;
    @ApiModelProperty(notes = "The database generated Student Name")
    private String name;
    @ApiModelProperty(notes = "The database generated Student Lastname")
    private String lastName;

    public Student(int id, long stdnumber, String name, String lastName) {
        this.id = id;
        this.stdnumber = stdnumber;
        this.name = name;
        this.lastName = lastName;
    }

    public int getId() {
        return id;
    }

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

    public long getStdnumber() {
        return stdnumber;
    }

    public void setStdnumber(long stdnumber) {
        this.stdnumber = stdnumber;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
}
Code language: JavaScript (javascript)

@ApiModelProperty

Bu modelimizde dikkat ettiyseniz. @ApiModelProperty(notes = ” “) anotasyonu kullandık. Modelimizdeki alanlarımızın açıklmasını buranın içerisine yazarak api dökümantasyonunda alanlarımızın açıklaması gözükmüş olacak. Görüntüsü aşağıdaki gibi olacaktır.

Model alanlarımızın Api dökümantasyonunda açıklamalı olarak gözükmesini bu şekilde sağlamaktayız eğer yazmazsak, açıklamalar olamadan bir modelimizin nesnesi olurdu.

Controllerimizi oluşturalım Controllerimizde tüm öğrencilerin listesini ve idsini girdiğimizde o öğrencinin bilgilerini getiren bir controller oluşturalım. Bu controllerımızın metodlarında gerekli Swagger anotasyonlarınıda inceleyeceğiz.

@RestController
@RequestMapping("/api")
@Api(value = "Student Rest Api", description = "Student Rest Service")
public class StudentController {
    @ApiResponses(
            value={
                    @ApiResponse(code = 403, message = "Forbidden"),
                    @ApiResponse(code = 404, message = "Not found"),
                    @ApiResponse(code = 500, message = "Server error")
            }
    )

    @ApiOperation(value = "List of Student"  )
    @GetMapping({"/", "/students"})
    public List<Student> getStudentList() {

        Map<Integer, Student> studentList = studentDatabase();
        return new ArrayList<>(studentList.values());
    }

    @ApiOperation(value = "Display selected Student")
    @GetMapping({"/students/{studentId}"})
    public Student getStudent(@PathVariable Integer studentId) {
       return studentDatabase().get(studentId);
    }

    private Map<Integer, Student> studentDatabase() {

        Map<Integer, Student> studentList = new HashMap<>();
        studentList.put(1, new Student(1, 1234, "Burak","Kutbay"));
        studentList.put(2, new Student(2, 5678, "Veli", "Ali"));
        return studentList;
    }
}
Code language: PHP (php)

Controllerimizi yakından inceleyelim ve Swagger anotasyonlarına bakalım.

@Api(value = “Student Rest Api”, description = “Student Rest Service”)

@Api anotasyonunda classımızın yani Rest servisimizin açıklamasını belirtiyoruz.

@ApiResponses ve @ApiResponse

Apimize gelen istekler ile alakalı geri dönüş mesajlarının ne ifade edeceğini özelleştirebilmemizi sağlar ve genel cevaplar haricinde farklı cevaplar verebiliriz.

@ApiOperation

@ApiOperation anotasyonun value değeri api methodlarının ne işe yaradığını açıklamamız sağlayan değerdir.

http://localhost:8080/swagger-ui.html adresine ulaştıktan sonra dökümantasyonumuz hazır görütüsü ise aşağıdaki gibi olacaktır.