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

Spring Boot
Spring Dersleri

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>

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"
        );
    }
}

@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.

Swagger Spring Boot Configuration

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;
    }
}

@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.

Swagger Model ApiModelProperty

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;
    }
}

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


Swagger Spring Boot Response Messages

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.

Swagger Api Operation

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.

Swagger2 Spring Boot Example

Kaynak Kodlara Github'tan UlaşBu yazıda anlatılan projenin kaynak kodlarını Github üzerinden indirebilirsiniz.
Önceki Ders: Spring Boot ile Hazelcast Kullanımı Uygulama Örneği
Spring Boot Dersleri
Sonraki Ders: 

Leave a Reply

E-posta hesabınız yayımlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir

Burak KUTBAY 2010 - 2020
%d blogcu bunu beğendi: