Swagger yazdığımız servislerin dökümantasyonunu yapan bir kütüphane. Dökümantasyonun önemini ve swagger’ı açıklayan hali hazırda bir yazımız mevcut. Orada problem güzel açıklandığı için öncelikle onu okumanızı tavsiye ederim. Biz Spring Boot tarafında nasıl implemente edeceğimize odaklanacağız.
Prrojemiz maven ve spring boot olacak. Pom.xml dosyamıza aşağıdaki dependencies ekliyoruz.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> |
HTTP metodlarını örneklemek için birden fazla metod yazacağım fakat odak noktamız servis ve repository katmanları olmadığı için ayrıca yazmayacağım. Controller’ımız ise aşağıdaki gibi olacak.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
@RestController public class UserController { @Autowired private UserService userService; @RequestMapping(value = "/users", method = RequestMethod.GET, produces = { "application/json" }) public List<User> getUser() { return userService.getAllUser(); } @RequestMapping(value = "/users/{id}", method = RequestMethod.GET, produces = { "application/json" }) public User getUser(@PathVariable(value = "id") Long userId) { return userService.getUserById(userId); } @RequestMapping(value = "/users", method = RequestMethod.POST, produces = { "application/json" }) @ResponseStatus(HttpStatus.CREATED) public User createUser(@Valid @RequestBody UserInput userInput) { User user = UserValidator.validate(userInput); return userService.saveUser(user); } @RequestMapping(value = "/users", method = RequestMethod.PUT, produces = { "application/json" }) public User updateUser(@RequestBody UserInput userInput) { User user = UserValidator.validate(userInput); return userService.updateUser(user); } @RequestMapping(value = "/users", method = RequestMethod.DELETE, produces = { "application/json" }) public String deleteUser(@RequestBody UserInput userInput) { User user = UserValidator.validate(userInput); userService.deleteUser(user); return "user deleted"; } } |
Servis metodlarımızdan sonra ise swagger konfigürasyonunu yapıyoruz.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket userApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() .apis(RequestHandlerSelectors.basePackage("com.bilisimio.controller")).paths(paths()).build(); } private Predicate<String> paths() { return PathSelectors.ant("/users"); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("User REST API").description("User API Documentation") .version("1.0").build(); } } |
Uygulamamızı çalıştırıp http://localhost:8080/swagger-ui.html adresine giderseniz aşağıdaki gibi bir sayfa göreceksiniz.
Eğer GET metodunun detayına gidip Try It Out diyip execute derseniz. Servisi sorgulayacaktır ve sonuçları getirecektir.
Sorgulama yapmadan da eğer uygulama 200, 401, 403 ve 404 alırsa ne döneceğini görebilirsiniz. Biz bu durumlar için geliştirme yapmadığımız için bir durum ifade etmiyor.
Not: Eğer siz de benim gibi Spring Security kullanıyorsunuz yukarıda söylediğim linke direkt olarak ulaşamazsınız. Şöyle bir konfigürasyon gereklidir.
|
1 2 3 4 5 6 7 8 9 |
@Override public void configure(WebSecurity web) throws Exception { web.ignoring().antMatchers("/v2/api-docs", "/configuration/ui", "**/swagger-resources/**", "/configuration/security", "/swagger-ui.html/**", "/webjars/**"); } |
Yazının fazla uzamaması için ikiye böldüm. İkinci bölümde görüşmek üzere.
Faydalı olması dileğiyle.