Giao tiếp mạng sử dụng Swagger trong React native

1. Swagger là gì?

Swagger là một bộ các công cụ mã nguồn mở được dùng để phát triển, thiết kế, xây dựng, và làm tài liệu cho các RESTful API.
Có một số phần mềm swagger như:

  • Swagger Editor: dùng để design các API mới hoặc edit các api có sẵn thông qua file spec.
  • Swagger Codegen: Dùng để sinh code từ file spec có sẵn.
  • Swagger UI: Dùng để sinh ra code html, js, css.. từ file spec, cung cấp 1 giao diện các apis để người phát triển app và người làm server đều có thể trực tiếp test các api trên đó.

2. Ưu điểm của swagger

Phía client:

  • Dễ dàng cập nhật API khi có sự thay đổi API từ phía server, ví dụ: thay đổi tham số, tên api..
  • Tự động sinh code dựa theo file spec nên việc xây dựng interface kết nối mạng ko còn khó khăn.

Phía server:

  • Tự động sinh document
  • Có thể thiết kế API xong trước rồi mới code.
  • Dễ dàng chia sẻ tài liệu api cho nhiều người.

3. Implement bên client như thế nào?

  • Cài đặt thư viện swagger-client: npm install swagger-client
  • Sử dụng như thế nào:
    1
    2
    3
    4
    5
    6
    7
    import Swagger from 'swagger-client'
    const Swag = new Swagger({
    spec,
    authorizations,
    requestInterceptor,
    responseInterceptor,
    })

trong đó:

  • spec là file json được tự động sinh ra từ bên phía server. File chứa mô tả các API, mỗi lần bạn muốn cập nhật API, thì chỉ cần thay đổi file này là được.
  • authorizations: chứa thông tin để xác thực request, được thêm vào trong phần header của mỗi request. Authorization keys được mô tả ở trong phần security của OpenAPI
    https://swagger.io/docs/specification/authentication/
  • requestInterceptor: như là điểm chốt chặn kiểm tra các request, tại đây bạn có thể sửa đổi, log lại request.
  • responseInterceptor: ngược lại với requestInterceptor, như là điểm chốt chặn của các response.

Ví dụ gọi API lấy thông tin của product.

1
2
3
4
5
6
7
8
9
const client = await Swagger
const resp = await client.apis.Product(
{id: productId}, // parameters
{ requestBody: {},
server: "https://api.xxx.jp"})
.catch(e=>e)
if (resp.ok) {
// handle response
}

Ta có thể thêm các tham số khác vào phần parameters với GET request, hoặc với POST, PUT request, ta thêm tham số vào phần requestBody.

4. Đánh giá chung.

  • Hiện tại ngoài js thì swagger client còn hỗ trợ hầu hết các ngôn ngữ khác nên việc phát triển ứng dụng multil-platforms khá thuận tiện.
  • Việc xây dựng api trở nên dễ dàng, sai sót giữa người làm client và server sẽ được hạn chế tối thiểu.
  • Thích hợp với các dự án lớn, nhiều người tham gia.

japanese

初めまして、タンと申します。ベトナムから参りました。
ブログ初投稿です。よろしくお願い致します。

1. 自己紹介

2015年にハノイ工科大学を卒業してから仕事で日本に来ました。大学生時代にObjective-Cとcocos2dx言語でアプリやゲームを開発したことがあります。
入社してWeb関係サービスを開発してRubyOnRailsというのフレームワークを触りました。
今ReactNativeでネイティブアプリのクロスクロスプラットフォームを開発しています。

今日はアプリ開発する時APIのコミュニケーションをできるようにSwaggerに関して紹介いたします。

2. Swaggerとは

SwaggerとはRESTfulAPIのドキュメントやサーバ、クライアントコード、設計できるツールです。

Swaggerツールの関係性関係性

  • Swagger Editor: 新しいAPIを作成と既存のAPIを編集、定義
  • Swagger Codegen: specファイルからコードを自動生成
  • Swagger UI: specファイルからアセットファイル(html, css, js)自動生成

3. Swaggerを使うメリット

サーバ側

  • APIドキュメントの自動生成ができる
  • APIモックを簡単に作成できる
  • クライアントに渡すAPIドキュメントをいちいち手書きすることもなくなるので便利です。

クライアント側:

  • APIの変更があればすぐにアップデートできる
  • ネットワークインターフェイスの作成がいらない

4. アプリ側でSwaggerの使い方

  • まず swagger-clientをインストール: npm install swagger-client
  • コードの追加:
    1
    2
    3
    4
    5
    6
    7
    import Swagger from 'swagger-client'
    const Swag = new Swagger({
    spec,
    authorizations,
    requestInterceptor,
    responseInterceptor,
    })

それぞれパラメタの説明:

  • spec: OpenAPI Specification, 記載ファイル
  • authorizations: リクエストのHEADに入ってるAuthorizationパラメタです。
    https://swagger.io/docs/specification/authentication/
  • requestInterceptor: ここでリクエストの情報をログできてパラメーターを変更することもできる。
  • responseInterceptor: ここでリスポンスの情報をログしたり変更することができます。

例:作品の情報を取得したい場合

1
2
3
4
5
6
7
8
9
const client = await Swagger
const resp = await client.apis.Product(
{id: productId}, // parameters
{ requestBody: {},
server: "https://api.xxx.jp"})
.catch(e=>e)
if (resp.ok) {
// handle response
}