Dựng các công cụ hỗ trợ phát triển API cho dự án dùng OpenAPI (Swagger)

Trong quá trình phát triển hệ thống, thông tường task có thể chia làm 2 phần frontend và backend. Đặc điểm của 2 phần này là có thể chạy song song được và giao tiếp với nhau bằng API.

Code UI trước, rồi xong api mới ghép vào thì nhiều vấn đề sẽ được phát hiện muộn (thiếu parameter , response, thiếu api...), và 1 số task phần ghép, call api lại ko làm làm trước.

Nếu dự án bạn sử dụng OpenAPI( tên cũ swagger), thì có thể tạo 1 môi trường mock cho api, và bạn cũng có thể dựng môi trường editor phục vụ cho việc phát triển/ chia sẻ API một cách thuận tiện.

docker-compose.yaml

 version: "3"
  services:
    swagger-editor:
      image: swaggerapi/swagger-editor
      container_name: "swagger-editor"
      ports:
        - "8081:8080"
      volumes:
        - ./:/work
      environment:
        - SWAGGER_FILE=/work/openapi-spec.yml
    swagger-ui:
      image: swaggerapi/swagger-ui
      container_name: "swagger-ui"
      ports:
        - "8080:8080"
      volumes:
        - ./openapi-spec.yml:/usr/share/nginx/html/openapi-spec.yml
      environment:
        API_URL: openapi-spec.yml
    swagger-api:
      image: stoplight/prism
      container_name: "swagger-api"
      ports:
        - "4010:4010"
      command: mock -h 0.0.0.0 /openapi-spec.yml
      volumes:
        - ./openapi-spec.yml:/openapi-spec.yml

Với file docker-compose.yml trên bạn sẽ dựng được 3 môi trường như bên dưới:

※ sample file openapi-spec.yml có thể lấy tại https://editor.swagger.io/

Swagger editor:

Cho phép bạn thiết kế với api

Giao diện Api document

Môi trường mock api:

Cho phép fontend có thể call api mặc dù api chưa được phát triển.

Bonus:

Nếu bạn muốn generate tài liệu api ra doc dạng html bạn có thể dùng  redoc-cli

redoc-cli bundle openapi-spec.yml -o api-doc.html

Với câu lệnh trên sẽ generate ra file html api document như bên dưới, để chia sẻ cho 1 bên thứ 3 nếu cần.