Tôi đã viết API Document cho dự án như thế nào?

Xin chào các bạn, hiện tại sau khi dự án của mình hoàn thành được phase 1 thì công việc cần thiết bây giờ là phải viết lại tài liệu dự án để sau này dễ dàng bảo trì, phát triển hoặc bàn giao dự án cho đội phát triển tiếp theo.

Đầu tiên mình nghĩ nó cũng chỉ đơn giản thôi, nhưng mà không. Lúc bắt tay vào làm thì mới thấy nó có nhiều cái phức tạp, và cái hay ho nhất mà mình thu về được đó là việc viết API document. Sau một hồi mình viết document bằng “cơm” thì được anh em khai sáng cho một số Tools hỗ trợ việc viết API document.

Và trong bài viết này, mình xin phép được chia sẻ một công cụ khá hay cũng như sơ qua cách sử dụng Laravel Api Doc Generator. Hi vọng rằng bài viết này có thể hỗ trợ cho những bạn “lần đầu làm chuyện ấy” giống như mình.

• Và sau một hồi tìm kiếm ở tận phương trời xa lắm, thì mình phát hiện ra là Laravel cũng có một công cụ hỗ trợ việc viết API Document.
• Sơ qua 1 chút thông tin trên github của laravel-apidoc-generator: Như các bạn có thể thấy thì commit mới nhất trên repo này là vào 15/6, tức là nó vẫn đang được phát triển liên tục.Còn về số sao mà cộng đồng đánh giá thì rơi vào khoảng 2000 sao, không phải quá cao nhưng cũng là 1 mức đáng ngưỡng mộ đối với một repo opensource mới.

  Với những thông tin trên thì bạn đã an tâm để sử dụng tool này chưa nào? Nếu rồi thì chúng ta cùng bắt đầu nhé!

• Yêu cầu cài đặt: tối thiểu PHP 7 và Laravel 5.5.
• Cài đặt:Cài đặt bằng composer:
  1 2 3 4

  composer required mpociot/laravel-apidoc-generator

  Khai báo trong service provider trong file bootstrap/app.php:

  1 2 3 4

  <span class="token variable">$app</span><span class="token operator">-</span><span class="token operator">&gt;</span><span class="token function">register</span><span class="token punctuation">(</span><span class="token package">Mpociot<span class="token punctuation"></span>ApiDoc<span class="token punctuation"></span>ApiDocGeneratorServiceProvider</span><span class="token punctuation">:</span><span class="token punctuation">:</span><span class="token keyword">class</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

  Tạo file config: sau khi chạy câu lệnh này, trong thư mục config của project sẽ xuất hiện file apidoc.php

  1 2 3 4

  php artisan vendor:publish --provider<span class="token operator">=</span><span class="token string">"MpociotApiDocApiDocGeneratorServiceProvider"</span> --tag<span class="token operator">=</span>apidoc-config

• Thử vọc vạch 1 số thứ trong config xem sao?
• Cách thức thực hiện:Cài đặt các thứ đã xong xuôi hết rồi, giờ thì chạy xem thành quả của mình nào.
  • B1: Sinh ra Api Doc:
  1 2 3 4

  php artisan apidoc:generate

  

  Sau khi quá trình này được hoàn tất, tài liệu HTML sẽ được ghi vào file: publicdocsindex.html

  • B2: Bật server và kiểm tra kết quả thu được

  Tiếp theo, hãy bật server lên với câu lệnh

  1 2 3 4

  php artisan serve

  Truy cập địa chỉ http://localhost:8000/docs/index.html để xem kết quả thu được nhé 

  Ở cột ngoài cùng bên trái là list những api được sử dụng trong project mà đã được lấy ra (trừ một số cái bị skip ở bước 1).

  Phần còn lại là thông tin chi tiết của API đấy:

  • Phương thức: GET/POST/PATCH/PUT/DELETE
  • Route:
  • Example request & example response:

Có người từng nói “Miếng phô mai có sẵn chỉ có ở trên bẫy chuột”. Vì vậy chúng ta không thể dùng ngay như bên trên được (chỉ là demo một chút cho các bạn thôi) mà phải cất công cấu hình một chút cho phù hợp với project và nhu cầu của bản thân!

Giờ thì cùng xem file config/apidoc.php có những thông số gì nào?

• output: đây là thiết lập đường dẫn cho file Document của bạn khi nó sinh ra. File document này được sinh ra là 1 file HTML và có chứa cả CSS, vì vậy hãy sử dụng đường dẫn tuyệt đối cho nó. Nếu bạn không thay đổi gì thì đường dẫn mặc định là public/docs
• router:
• base_url: base URL sẽ được sử dụng cho các ví dụ và Postman collection. Giá trị mặc định của base URL được lấy trong config(app.url)
• postman: không chỉ tạo ra một file document thông thường, laravel-apidoc-generator còn hỗ trợ sinh ra Postman Collection (nếu chưa biết về Postman thì bạn có thể tìm hiểu ở đây nhé)
  • enabled: có sinh ra Postman Collection hay không. Giá trị mặc định ở đây là true
  • name: đặt tên cho collection được xuất ra. Nếu bạn để trống thì sẽ lấy tên mặc định từ config('app.name')."API"
  • description: mô tả chi tiết cho collection
• logo: thay vì sử dụng logo mặc định, bạn có thể tùy chỉnh logo của project của bạn trong file Document. Cũng giống như output, bạn phải sử dụng đường dẫn tuyệt đối đến file logo của bạn. Chú ý: ảnh logo nên để kích thước 230 x 52.
  
  1 2 3 4

  <span class="token single-quoted-string string">'logo'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token function">resource_path</span><span class="token punctuation">(</span><span class="token single-quoted-string string">'views'</span><span class="token punctuation">)</span> <span class="token punctuation">.</span> <span class="token single-quoted-string string">'/api/logo.png'</span>

• fractal (nếu chưa biết đến fractal thì bạn có thể tìm hiểu ở đây fractal/transformers):
• routes: phần này được lưu trữ dưới dạng mảng các route, mỗi route chứa một số quy định xem routes nào thuộc group nào, áo dụng những quy định nào. Điều này giúp cho chúng ta có thể tuỳ chỉnh những chi tiết cho từng route.
  • match: xác định các quy định được sử dụng trong route thuộc một group. Có 3 loại rules được định nghĩa ở đây:
    • domains: trong 1 project có thể có
    • prefixes: đây là phần tiền tố cho các route. Kiểu như các route có domain và prefix chỉ định thì sẽ áp dụng các rule chỉ định. Ví dụ như sau:
    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

    <span class="token php language-php"><span class="token delimiter important">&lt;?php</span> <span class="token keyword">return</span> <span class="token punctuation">[</span>   <span class="token single-quoted-string string">'routes'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span>     <span class="token comment">//những route có tiền tố là users hoặc apps thì sẽ cần xác thực người dùng, sử dungj authorization truyền trong headers</span>     <span class="token punctuation">[</span>       <span class="token single-quoted-string string">'match'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span>          <span class="token single-quoted-string string">'domains'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span><span class="token single-quoted-string string">'*'</span><span class="token punctuation">]</span><span class="token punctuation">,</span>          <span class="token single-quoted-string string">'prefixes'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span><span class="token single-quoted-string string">'users/*'</span><span class="token punctuation">,</span> <span class="token single-quoted-string string">'apps/*'</span><span class="token punctuation">]</span><span class="token punctuation">,</span>        <span class="token punctuation">]</span><span class="token punctuation">,</span>        <span class="token single-quoted-string string">'apply'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span>          <span class="token single-quoted-string string">'headers'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span> <span class="token single-quoted-string string">'Authorization'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token single-quoted-string string">'Bearer {your-token}'</span><span class="token punctuation">]</span>        <span class="token punctuation">]</span>     <span class="token punctuation">]</span><span class="token punctuation">,</span>     <span class="token comment">// còn những route có tiền tố là stats, status thì public và không cần xác thực</span>     <span class="token punctuation">[</span>       <span class="token single-quoted-string string">'match'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span>          <span class="token single-quoted-string string">'domains'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span><span class="token single-quoted-string string">'*'</span><span class="token punctuation">]</span><span class="token punctuation">,</span>          <span class="token single-quoted-string string">'prefixes'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span><span class="token single-quoted-string string">'stats/*'</span><span class="token punctuation">,</span> <span class="token single-quoted-string string">'status/*'</span><span class="token punctuation">]</span><span class="token punctuation">,</span>       <span class="token punctuation">]</span><span class="token punctuation">,</span>     <span class="token punctuation">]</span><span class="token punctuation">,</span>   <span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token punctuation">]</span><span class="token punctuation">;</span> </span>

    • versions: đây là đánh số phiên bản cho các route. CHÚ Ý: phần này chỉ hoạt động nếu bạn sử dụng Dingo Router.
  • apply: sau khi định nghĩa trong match, trong phần apply sẽ chỉ định những thiết lập được áp dụng cho những routes này khi chạy lệnh generate.
    • headers: phần header này sẽ được hiển thì trong phần example requests trong tài liệu (cột đen ở phía bên phải màn hình ấy). Headers được khai báo dưới dạng key => value như thế này:
      
      1 2 3 4 5 6 7

      <span class="token single-quoted-string string">'headers'</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">[</span>     <span class="token single-quoted-string string">'Authorization'</spa Bình luận về bài viết này Vũ Văn Thanh 12 chủ đề 2597 bài viết Có thể bạn quan tâm 1 Client-side rendering vs Server-side rendering – Đâu là sự lựa chọn của bạn 2 Google I/O 2019 – Thay đổi trong các Android Architecture Components (P1) 3 Tự build mạng lưới đơn giản nhận diện biển báo giao thông 4 [Java log] P2: Tích hợp log4j vào phần mềm 5 Hàm format() trong Python 6 Hàm iter() trong Python 7 Những biến thể phần mềm độc hại phổ biến sử dụng Process Doppelgänging để tránh bị phát hiện 8 Growth hacking một loại hình nghệ thuật mới dành cho lập trình viên 9 Lập trình hướng chức năng đang thống trị mảng UI với Pure Views. 10 12 sinh viên Đại học Bách khoa Hà Nội mới ra trường nhận lương 138 triệu đồng/tháng 0 Các chủ đề đang được quan tâm phần mềm lập trình php | lập trình web php + mysql | khóa học lập trình php | tự học lập trình php | học php cơ bản thachpham | Code24h | Cho thuê phòng trọ hà nội | Cho thuê phòng trọ bình thạnh | Cho thuê phòng trọ | Cho thuê nhà trọ Đăng ký Đăng ký nhận thông báo Các bài học thú vị sẽ được gửi đến inbox của bạn HỖ TRỢ HỌC VIÊN Các câu hỏi thường gặp Điều khoản sử dụng Chính sách và quy định Chính sách bảo mật thanh toán Hỗ trợ học viên: hotro@code24h.com Báo lỗi bảo mật: security@code24h.com VỀ CODE24H Giới thiệu Code24h Cơ hội nghề nghiệp Liên hệ với chúng tôi HỢP TÁC VÀ LIÊN KẾT Đăng ký giảng viên Giải pháp e-learning Chương trình đại lý Chương trình Affiliate KẾT NỐI VỚI CHÚNG TÔI TẢI ỨNG DỤNG TRÊN ĐIỆN THOẠI CCode 24h, code mọi lúc, mọi nơi © Copy right 2018 - 2024