آموزش Spring REST ساخت REST Client توسط Swagger CodeGen

در این بخش خواهیم دید چگونه با Swagger CodeGen تحت تعاریف Swagger specification/Open API یک Spring Boot REST Client بسازیم 

ساخت REST Client :

swagger یک ابزار جداگانه بصورت کتابخانه دارد (code-gen_cli.jar) که این امکان را میدهد که از روی داکیومنت موجود کلاینت آنرا بسازد که میتوان از آن کلاینت در بسیاری از زبان های برنامه نویسی و فریم ورک های دیگر استفاده کرد 

کتابخانه code-gen_cli.jar را میتوان از اینجا دریافت کرد و یا جدیدترین ورژن انرا در مخزن Maven جستجو کرد

برای ساخت کلاینت کافی است از طریق خط فرمان پارامتر های مورد نیاز را ارسال کرد :

java -jar swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  --api-package com.baeldung.petstore.client.api \
  --model-package com.baeldung.petstore.client.model \
  --invoker-package com.baeldung.petstore.client.invoker \
  --group-id com.baeldung \
  --artifact-id spring-swagger-codegen-api-client \
  --artifact-version 0.0.1-SNAPSHOT \
  -l java \
  --library resttemplate \
  -o spring-swagger-codegen-api-client

سویچ i- آدرس منبع swagger را میپذیرد

با api-package, –model-package, –invoker-package-- نام پکیچ هایی که میخواهیم کلاس ها در آن قرار بگیرند تعریف میشود

با group-id, –artifact-id, –artifact-version-- پراپرتی های مربوط به Maven را مشخص میکنیم

با l- زبان برنامه نویسی مورد استفاده در کلاینت را تعیین میکنیم 

با library-- فریم ورک مورد استفاده را مشخص میکنیم 

و با o-- مسیری است که کلاینت ساخته شده در آنجا قرار میگیرد

برای دیدن توضیح کامل میتوانیم دستور زیر را وارد کنیم :

java -jar swagger-codegen-cli.jar config-help -l java

Swagger Code Generation از کتابخانه های زیر که ترکیبی از Http Client و JSON  حمایت میکند :

jersey1 – Jersey1 + Jackson

jersey2 – Jersey2 + Jackson

feign – OpenFeign + Jackson

okhttp-gson – OkHttp + Gson

retrofit (Obsolete) – Retrofit1/OkHttp + Gson

retrofit2 – Retrofit2/OkHttp + Gson

rest-template – Spring RestTemplate + Jackson

rest-easy – Resteasy + Jackson

 

که ما از rest-template که بخشی از اکوسیستم اسپرینگ است استفاده کردیم 

حال پروژه را بر مبنای Spring Boot ایجاد میکنیم :

ابتدا وابستگی ها را اضافه میکنیم :

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>spring-swagger-codegen-api-client</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

برای دسترسی به کلاس های تولید شده نیاز به ایجاد انها به عنوان Bean هستیم :

@Configuration
public class PetStoreIntegrationConfig {
 
    @Bean
    public PetApi petApi() {
        return new PetApi(apiClient());
    }
     
    @Bean
    public ApiClient apiClient() {
        return new ApiClient();
    }
}

تنظیمات API Client : 

کلاس ApiClient زیر برای تنظیم کردن موارد امنیتی احراز هویت ، مسیر اصلی دسترسی به API ، هدر های مشترک و همچنین وظیفه اجرای کلیه درخواست های API را بر عهده دارد 

برای نمونه برای ست کردن احراز هویت تحت OAuth :

@Bean
public ApiClient apiClient() {
    ApiClient apiClient = new ApiClient();
 
    OAuth petStoreAuth = (OAuth) apiClient.getAuthentication("petstore_auth");
    petStoreAuth.setAccessToken("special-key");
 
    return apiClient;
}

از کلاس PetStoreIntegrationConfig استفاده میکنیم برای ست کردن تنظیمات پیش فرض و آنرا Import@ میکنیم :

@SpringBootApplication
@Import(PetStoreIntegrationConfig.class)
public class PetStoreApplication {
    public static void main(String[] args) throws Exception {
        SpringApplication.run(PetStoreApplication.class, args);
    }
}

طریقه استفاده از Bean های کلاینت :

از آنجا که ما کلاس های کلاینت را بصورت Bean تعریف کردیم میتوانیم انها را در پروژه تزریق کنیم :

@Autowired
private PetApi petApi;
 
public List<Pet> findAvailablePets() {
    return petApi.findPetsByStatus(Arrays.asList("available"));
}

جالب بود نه ؟ اینطوری وقت بسیار زیادی را در مرحله توسعه محصول ذخیره کردیم و از این حیث بسیار سریع محصول آماده استفاده خواهد بود در شرایطی مثل وجود پروژه های استارت آپ نقش این ابزار ها پر رنگ تر خواهند شد

روش های دیگر برای تولید کلاینت :

یکی دیگر از روش ها استفاده از پلاگین Maven کتابخانه Swagger CodeGen است 

کافی است آنرا به pom پروژه به عنوان یک پلاگین اضافه کنیم . تنظیمات زیر باعث میشود کلاینت اتوماتیک ساخته شود :

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.2.3</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>swagger.yaml</inputSpec>
                <language>java</language>
                <library>resttemplate</library>
            </configuration>
        </execution>
    </executions>
</plugin>

راه دیگر استفاده از ابزار آنلاین است :

کافی است یک درخواست POST به همراه ادرس مشخصه های API به آدرس http://generator.swagger.io/api/gen/clients/java ارسال کنیم در جواب ممکن است بصورت JSON همراه با لینک دانلود یا یک فایل فشرده قابل دانلود باشد 

در این روش هم ما میتوانیم موارد انتخابی که در روش خط فرمان Swagger Codegen CLI  داشتیم را بکار ببریم که برای اطلاعات بیشتر میتوانیم به آدرس https://generator.swagger.io/ مراجعه کنیم