Top #10 Xem Nhiều Nhất Cách Viết Api Document Mới Nhất 5/2022 # Top Like

--- Bài mới hơn ---

Tôi Đã Viết Api Document Cho Dự Án Như Thế Nào?

Viết Api Document Cho Dự Án Sử Dụng Laravel

Tạo Ứng Dụng Android Đơn Giản Đưa Lên Google Play Trong 10 Tiếng

Cách Tạo Ứng Dụng Android / Ios Không Cần Biết Lập Trình

Appendix: Cách Tiếp Cận Trung Tâm

Như các bạn đã biết, 1 ứng dụng API sẽ không có giao diện cho người dùng trên trình duyệt, thay vào đó sẽ là các dữ liệu kiểu JSON hoặc XML … được hiển thị mà thôi. Do đó, khi viết 1 ứng dụng API đòi hỏi người viết phải viết Documents (Tài liệu) kèm theo để hỗ trợ cho những Developers sử dụng chúng và đặc biệt là QA, những người sẽ gặp nhiều khó khăn hơn trong việc hiểu được tác dụng của các API.

Có nhiều cách để viết Documents, đơn giản nhất sẽ là viết bằng tay ra file Excel hoặc Word chẳng hạn. Chỉ rõ API này mục đích làm gì, URL để truy cập đến như thế nào, dữ liệu gửi Request là gì, Dữ liệu Response trả về là gì … Xong rồi thì gửi chúng cho bên Developers/QA có như cầu sử dụng để họ đọc. Cách này khá thủ công và tốn nhiều efforts trong khi giá trị mang lại cho những người sử dụng chúng lại chưa chắc đã cao, vì đơn giản chúng không có 1 Format thống nhất và rất dễ thiếu thông tin.

Hôm nay mình sẽ giới thiệu cho các bạn 1 Tool khá nổi tiếng trong việc viết API docs, đó là Swagger (UI). Cụ thể Swagger là gì thì các bạn có thể search để tìm hiểu, Swagger nên ở phạm vi bài viết này mình xin phép không giới thiệu lại, thay vào đó sẽ mình sẽ đi sâu vào cách triển khai Swagger theo cách “Khoa học” và “Developer” nhất có thể.

Quay lại 1 chút thì các bài viết trước đây khi hướng dẫn triển khai Swagger UI thường tiếp cận theo hướng copy UI của Swagger rồi “ném” vào Project của mình (clone lại Repository Swagger hoặc copy file CSS, JavaScript của Swagger) không thì viết sẵn 1 file XML (JSON) rồi render lại chúng ra View.

Còn cách mà “Khoa học” và theo hướng “Developers” ở đây mình muốn nói đến là:

• Có khả năng tái sử dụng code, viết Docs cũng như viết Code, cái gì giống nhau là gọi lại dùng được
• Dễ dàng mở rộng (Scale), ví dụ: khi thêm 1 trường vào Model hay đổi tên 1 trường chẳng hạn thì file Documents cũng tự động được update chẳng hạn
• Tổ chức Trees (Cây thư mục) rõ ràng và khoa học

Trong Rails thì có 2 Gem thường được dùng để Implement Swagger là: swagger-docs và swagger-blocks. Sự khác biệt lớn nhất giữa 2 Gem này là swagger-blocks được support đến v2.0 của Swagger Specification còn swagger-docs chỉ dừng lại ở v1.2, và theo thông tin trên Repo của swagger-docs thì họ chưa có kế hoạch update lên v2.0. Do đó trong Demo này mình sẽ triển khai với gem swagger-blocks.

Note: cả 2 gem kể trên đều không sinh ra giao diện UI/UX theo kiểu Swagger mà chỉ sinh ra 1 file .json phù hợp với format của Swagger UI mà thôi, do đó để có giao diện như Swagger mang lại, chúng ta cần 1 Gem nữa là swaggeruiengine.

Bắt đầu, tạo 1 ứng dụng Rails API bằng cách gõ các lệnh sau trên Terminal:

Sau đó add thêm 2 Gem mình giới thiệu phía trên vào Gemfile rồi bundle chúng:

Note: khi triển khai thực tế mình gặp phải 1 vấn đề khi call API bằng tool Postman – tool hỗ trợ test các Request API – thì Oki nhưng khi Deploy lên Server và call API qua lại giữa các Server thì bị trả về 404, sau 1 hồi search thì tìm hiểu ra là do thiếu config CORS. Để khắc phục thì bạn chỉ cần add thêm vào Gem như sau:

và config cho Rails như sau:

Trên Repo của gem Swagger-Blocks có giới thiệu khá chi tiết về cách Setup Swagger, tuy nhiên mình thấy 1 số điểm chưa thực sự “dry” code cho lắm, do đó mình sẽ custom lại Trees (cấu trúc) của Swagger trong Project của mình 1 chút để tận dụng được những cái sài chung (tái sử dụng code í mà) như kiểu các Paramerter hay được gọi đi gọi là hoặc là các Response phổ biến (lỗi 404 hay 500 chẳng hạn). Đồng thời cũng giúp chúng ta dễ dàng mở rộng code khi cần thiết trong tương lai.

Cấu trúc thư mục của Swagger khi đó sẽ như thế này:

So sánh với tài liệu trên Repo của Swagger-Blocks thì cách tổ chức của mình có 1 vài điểm mà cá nhân mình nghĩ sẽ rành mạch và rõ ràng hơn.

• Theo Swagger hướng dẫn thì mỗi Documents sẽ ứng với 1 Controller, cách viết này khá dễ hiểu, nhưng các bạn có thế dễ dàng nhận ra là Controller sẽ bị phình to “cực kỳ” nhanh nếu đặt Docs trong đó. Và Controller cũng không phải là là 1 nơi lý tưởng để xử lý Docs. Do đó, chúng ta hãy tách ra thành 1 Module riêng biệt – chuyển xử lý Docs. Cụ thể ở đây mình sẽ để vào trong thư mục concern/swagger rồi sau đó Include lại vào Controller.
• Sẽ có rất nhiều Parameter dùng chung, ví dụ: userID được dùng chung khi get thông tin của User cũng như update thông tin user chẳng hạn. Do đó mình tạo ra 1 file chúng tôi để chứa những thứ dùng chung, khi cần dùng thì sẽ include lại vào file Docs (ở đây là user_api.rb)
• Tương tự, sẽ có rất nhiều Response Error được dùng chung, kiểu lỗi 401 – not authorize hay là 404 – not found Records do đó mình tạo ra 1 file error_response.rb để viết chung, khi cần lại include vào file chứa Docs (ở đây là user_api.rb)
• Response Success 200 tuy mỗi API sẽ trả về 1 thông tin khác nhau, nhưng không phải là không có điểm chung. Chẳng hạn, các API sau đều trả về thông tin của User sau khi Request thành công đó là: API show, API edit thông tin của User và API login. Do đó, chúng ta phải tìm cách tái sử dụng Code. May thay, với Swagger chúng ta có thể sử dụng $ref để gọi tới 1 schema được định nghĩa trước đó (ở đây là: user_schema.rb trong modes/concern/swagger)

Chú ý cần tạo Router cho Documents để còn biết URL mà xem trên trình duyệt.

Sau khi tạo Router, thì chúng ta cũng tạo ra 1 controller ứng với router này và định nghĩa các thông số cơ bản của API Documents như:

• Version Swagger sử dụng -Tittle, Description của API
• Đường dẫn mặc định của API
• Kiểu dữ liệu sinh ra của API (thường là Json hoặc có thể là XML) ….

Trong method index của api_docs_controller các bạn nhớ gọi method để render ra những thông tin API mà mình muốn viết Docs.

Đến đây là các bạn có thể bật server lên và vào URL: localhost:3000/api_docs.json để xem thanh quả rồi.

Chúng ta sẽ dùng gem swagger_ui_engine và config 1 chút để có giao diện Swagger UI cho dữ liệu json mình vừa tạo ra ở bên trên như sau:

Xong. Tới đây bạn có thể restart lại server, truy cập lại URL localhost:3000/api_docs để thấy thành quả.

--- Bài cũ hơn ---

Giới Thiệu Tool Swagger Ui

Học Kiểm Thử Api Trong 10 Phút

Cách Tạo Api Với Rails (Phần 2) Viết Test Case

How To Write Test Cases ( Hướng Dẫn Cách Viết Testcases)

Làm Thế Nào Để Viết Testcase Cho Người Mới Bắt Đầu

--- Bài mới hơn ---

Cách Gõ Biểu Tượng Logo Apple

Mẹo Làm Bài Thi B1 Preliminary (Pet) Format 2022 (2): Phần 1 Bài Thi Viết – Writing – Aspect

Cách Viết Bản Kiểm Điểm Nói Chuyện Trong Giờ Học

Cách Viết Thư Xin Lỗi Bằng Tiếng Nhật Gửi Ngoài Công Ty

Đi Học Muộn, Học Sinh Viết Bản Kiểm Điểm “bá Đạo” Khiến Dân Tình Cườ

Document là thứ rất quan trọng khi bàn giao một dự án hay cần tham khảo để bảo trì, phát triển dự án đó. Một số bạn dev sẽ nói mình viết code đẹp rồi, cứ vào đọc là hiểu ngay cần gì làm doc và thẳng thừng nói không với doc. Nhưng khi download một source code về, nhận code từ dev khác hay vào maintain một project thì khóc ròng vì không hiểu người ta viết gì cả. Vậy nên:

1. Nếu bạn định code cái gì, hãy dành thời gian ra viết một chút document cho nó

2. Nếu bạn không cập nhật document thì đừng viết nó ra

Với API, dù bạn viết code đẹp thế nào mà không có gì cho client tham khảo ngoài một API mẫu thì khối API bạn viết sẽ sớm trở thành thảm họa với những lỗi kinh điển như: sai kiểu dữ liệu gửi nhận, sai mã lỗi, tốn thời gian support client, mất kiểm soát khi nâng cấp API version… sau đó thì kiểu gì bạn cũng phải ngồi viết document.

npm install apidoc -g

Các thức hoạt động

Folder api-document-output là output của chương trình được generate tự động, bạn không cần đụng tới nó, chỉ cần mở file index.html để xem kết quả.

Bắt đầu viết doc như sau, tạo một file có đuôi cùng với ngôn ngữ bạn dùng để viết API, trong trường hợp này là .js, viết toàn bộ thông tin về một API theo mẫu thế này:

/** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup User * * @apiParam {Number} id Users unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. * * @apiSuccessExample Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } * * @apiError UserNotFound The id of the User was not found. * * @apiErrorExample Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */

apidoc -i api-document-source/ -o api-document-output/

Với param -i, -o đơn giản là input folder, output folder. Sau đó mở file index.html trong folder out put để xem kết quả.

Giao diện đơn giản trình bày tất cả API trong một trang, navigate bằng menu bên trái, toàn bộ chi tiết trình bày ở giữa trang

Happy documentation 🙂

--- Bài cũ hơn ---

Cách Đổi Font Chữ Trên Story Facebook Siêu Dễ Ai Cũng Làm Được

Cách Làm Menu Đẹp Siêu Đơn Giản Mà Ấn Tượng

Cách Viết Chữ Kiểu Trên Facebook Trên Điện Thoại

Phần Mềm Tạo Chữ Ký Online Cực Đẹp Theo Tên Của Bạn

Mẫu Chữ Ký Đẹp

--- Bài mới hơn ---

Cách‌ ‌viết‌ ‌cover‌ ‌letter‌ ‌tiếng‌ ‌anh‌ ‌đỉnh Cao‌

11 Tài Liệu Lập Trình Ios Miễn Phí Hay Nhất

Khóa Học Lập Trình Ứng Dụng Android Trong 24 Giờ – Free

Tự Học Lập Trình Android Từ A

Thiết Kế App Bán Hàng Online

Structure parameter like:

• @apiDefine

is used to define a reusable documentation block. This block can be included in normal api documentation blocks. Using @apiDefine allows you to better organize complex documentation and avoid duplicating recurrent blocks.

A defined block can have all params (like @apiParam), except other defined blocks.

@api

@api {method} path

Describe the request body passed to your API-Method.

Usage: @apiBody {type} {key: value}

Name

Description

{type}

optional

Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String

Fieldname with brackets define the Variable as optional.

field Optional Firstname of the User. * @apiParam {String} lastname Mandatory Lastname. * @apiParam {String} country="DE" Mandatory with default value "DE". * @apiParam {Number} Optional nested address object. * @apiParam {String} ] Optional zip code. * @apiParam {String}

Mark an API Method as depcated

Usage: @apiDepcated use now (#Group:Name).

Name

Description

text

Multiline text.

Example:

/** * @apiDepcated */ /** * @apiDepcated use now (#Group:Name). * * Example: to set a link to the GetDetails method of your group User * write (#User:GetDetails) */

@apiDescription

@apiDescription text

Detailed description of the API Method.

Usage: @apiDescription This is the Description.

Name

Description

text

Multiline description text.

Example:

/** * @apiDescription This is the Description. * It is multiline capable. * * Last line of Description. */

@apiError

@apiError field } (array of strings), …

field

Return Identifier (returned error code).

description

optional

Description of the field.

Example:

/** * @api {get} /user/:id */

@apiErrorExample

@apiErrorExample example

Example of an error return message, output as a p-formatted code.

Usage: @apiErrorExample {json} Error-Response:

This is an example.

Name

Description

type

optional

Response format.

title

optional

Short title for the example.

example

Detailed example, multilines capable.

Example:

/** * @api {get} /user/:id * @apiErrorExample {json} Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */

@apiExample

@apiExample } (array of strings), …

field

Variablename.

Place it on top of a block.

A block with @apiIgnore will not be parsed. It is usefull, if you leave outdated or not finished Methods in your source code and you don’t want to publish it into the documentation.

Usage: @apiIgnore Not finished Method

Name

Description

hint

optional

Short information why this block should be ignored.

Example:

/** * @apiIgnore Not finished Method * @api {get} /user/:id */

@apiName

@apiName name

Should always be used.

Defines the name of the method documentation block. Names will be used for the Sub-Navigation in the

generated output. Structure definition not need @apiName.

Usage: @apiName GetUser

Name

Description

name

Unique name of the method. Same name with different @apiVersion can be defined.

Format: method + path (e.g. Get + User), only a proposal, you can name as you want.

Also used as navigation title.

Example:

/** * @api {get} /user/:id * @apiName GetUser */

@apiParam

@apiParam

Describe a parameter passed to you API-Method.

Usage: @apiParam (MyGroup) {Number} id Users unique ID.

For nested parameters, use square bracket notation (} (array of strings), …

{type{size}}

optional

Information about the size of the variable.

{string{..5}} a string that has max 5 chars.

{string{2..5}} a string that has min. 2 chars and max 5 chars.

{number{100-999}} a number between 100 and 999.

{type=allowedValues}

optional

Information about allowed values of the variable.

{string="small"} a string that can only contain the word “small” (a constant).

{string="small","huge"} a string that can contain the words “small” or “huge”.

{number=1,2,3,99} a number with allowed values of 1, 2, 3 and 99.

Can be combined with size:

{string {..5}="small","huge"} a string that has max 5 chars and only contain the words “small” or “huge”.

field

Fieldname.

Mandatory nested field.

=defaultValue

optional

The parameters default value.

description

optional

Description of the field.

Examples:

/** * @api {get} /user/:id * @apiParam {Number} id Users unique ID. */ /** * @api {post} /user/ * @apiParam {String} Optional Age with default 18. * * @apiParam (Login) {String} pass Only logged in users can post this. * In generated documentation a separate * "Login" Block will be generated. * * @apiParam {Object} ] Optional street and number. * @apiParam {String} ] Optional city. */

@apiParamExample

@apiParamExample example

Parameter request example.

Usage: @apiParamExample {json} Request-Example:

{ "content": "This is an example content" }

Name

Description

type

optional

Request format.

title

optional

Short title for the example.

example

Detailed example, multilines capable.

Example:

/** * @api {get} /user/:id * @apiParamExample {json} Request-Example: * { * "id": 4711 * } */

@apiPermission

@apiPermission name

Outputs the permission name. If the name is defined with @apiDefine the generated documentation include the additional title and description.

Usage: @apiPermission admin

Name

Description

name

Unique name of the permission.

Example:

/** * @api {get} /user/:id * @apiPermission none */

@apiPrivate

@apiPrivate

Defines an API as being private to allow the creation of two API specification documents: one that excludes the private APIs and one that includes them.

Usage: @apiPrivate

Example:

/** * @api {get} /user/:id * @apiPrivate */

@apiBody

@apiQuery } (array of strings), …

{type{size}}

optional

Information about the size of the variable.

{string{..5}} a string that has max 5 chars.

{string{2..5}} a string that has min. 2 chars and max 5 chars.

{number{100-999}} a number between 100 and 999.

{type=allowedValues}

optional

Information about allowed values of the variable.

{string="small"} a string that can only contain the word “small” (a constant).

{string="small","huge"} a string that can contain the words “small” or “huge”.

{number=1,2,3,99} a number with allowed values of 1, 2, 3 and 99.

Can be combined with size:

{string {..5}="small","huge"} a string that has max 5 chars and only contain the words “small” or “huge”.

field

Fieldname.

Mandatory nested field.

=defaultValue

optional

The parameters default value.

description

optional

Description of the field.

Examples:

/** * @api {get} /user/:id * @apiQuery admin */

@apiSampleRequest

@apiSampleRequest url

Use this parameter in conjunction with the chúng tôi configuration parameter sampleUrl.

If sampleUrl is set, all methods will have the api test form (the endpoint from @api will be appended).

Without sampleUrl only methods with @apiSampleRequest will have a form.

if @apiSampleRequest url is set in a method block, this url will be used for the request (it overrides sampleUrl when it starts with http).

If sampleUrl is set and you don’t want a method with a test form, then add @apiSampleRequest off to the documentation block.

Usage: @apiSampleRequest http://test.github.com

Name

Description

url

Url to your test api server.

Overwrite the configuration parameter sampleUrl and append @api url:

@apiSampleRequest http://www.example.com

Prefix the @api url:

@apiSampleRequest /my_test_path

Disable api test if configuration parameter sampleUrl is set:

@apiSampleRequest off

Examples:

This will send the api request to http://api.github.com/user/:id

Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id */

This will send the api request to http://test.github.com/some_path/user/:id

It overwrites sampleUrl.

Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id * @apiSampleRequest http://test.github.com/some_path/ */

This will send the api request to http://api.github.com/test/user/:id

It extends sampleUrl.

Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id * @apiSampleRequest /test */

This will disable the api request for this api-method.

Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id * @apiSampleRequest off */

This will send the api request to http://api.github.com/some_path/user/:id

It activates the request for this method only, because sampleUrl is not set.

Configuration parameter sampleUrl is not set /** * @api {get} /user/:id * @apiSampleRequest http://api.github.com/some_path/ */

@apiSuccess

@apiSuccess field } (array of strings), …

field

Return Identifier (returned success code).

description

optional

Description of the field.

Example:

/** * @api {get} /user/:id * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */

Example with (group), more group-examples at @apiSuccessTitle:

/** * @api {get} /user/:id * @apiSuccess (200) {String} firstname Firstname of the User. * @apiSuccess (200) {String} lastname Lastname of the User. */

Example with Object:

/** * @api {get} /user/:id * @apiSuccess {Boolean} active Specify if the account is active. * @apiSuccess {Object} profile User profile information. * @apiSuccess {Number} chúng tôi Users age. * @apiSuccess {String} profile.image Avatar-Image. */

Example with Array:

/** * @api {get} /users * @apiSuccess {Object [title] example

Example of a success return message, output as a p-formatted code.

Usage: @apiSuccessExample {json} Success-Response:

{ "content": "This is an example content" }

Name

Description

type

optional

Response format.

title

optional

Short title for the example.

example

Detailed example, multilines capable.

Example:

/** * @api {get} /user/:id * @apiSuccessExample {json} Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } */

@apiUse

@apiUse name

Include a with @apiDefine defined block. If used with @apiVersion the same or nearest pdecessor will be included.

Usage: @apiUse MySuccess

Name

Description

name

Name of the defined block.

Example:

/** * @apiDefine MySuccess * @apiSuccess {string} firstname The users firstname. * @apiSuccess {number} age The users age. */ /** * @api {get} /user/:id * @apiUse MySuccess */

@apiVersion

@apiVersion version

Set the version of an documentation block. Version can also be used in @apiDefine.

Blocks with same group and name, but different versions can be compared in the generated output, so you or a frontend developer can retrace what changes in the API since the last version.

Usage: @apiVersion 1.6.2

Name

Description

version

Simple versioning supported (major.minor.patch). More info on Semantic Versioning Specification (SemVer).

Example:

/** * @api {get} /user/:id * @apiVersion 1.6.2 */

For more watch versioning example.

--- Bài cũ hơn ---

Cách Tạo Một Web Api Đơn Giản Bằng Asp.net

Hướng Dẫn Viết Essay Tiếng Anh Ngắn Nhưng Chất Lượng

10 Cách Nói Cảm Ơn Thay Cho Câu “thank You!” Nhàm Chán!

Hướng Dẫn Chi Tiết Cách Viết Thiệp Cưới Được Lòng Khách Mời

Chữ Ký Tên Quỳnh – Các Kiểu Chữ Ký Tên Quỳnh Đẹp,ý Nghĩa Nhất

--- Bài mới hơn ---

Tạo Ứng Dụng Android Đơn Giản Đưa Lên Google Play Trong 10 Tiếng

Cách Tạo Ứng Dụng Android / Ios Không Cần Biết Lập Trình

Appendix: Cách Tiếp Cận Trung Tâm

Appendix: Cách Tiếp Cận Kiểm Soát Dịch Vụ

Appraisal Là Gì? Mục Tiêu Và Vai Trò Cụ Thể Như Thế Nào ?

Xin chào mọi người. Hiện tại mình đang phát triển 1 dự án kết hợp Laravel API và reactjs và việc để dễ dàng phối hợp giữa 2 team frontend và backend và cần 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 nên dự án có yêu cầu viết document cho API, sau 1 thơi gian tìm hiểu và áp dụng thì mình xin phép chia sẻ một số kiến thức với mọi người. Về viết document cho laravel API thì mình sử dụng packet Laravel API Documentation Generator

Cài đặt

Chạy lệnh để cài đặt thư viện

composer require --dev mpociot/laravel-apidoc-generator

Xuất bản tệp cấu hình bằng cách chạy lệnh:

php artisan vendor:publish --provider="MpociotApiDocApiDocGeneratorServiceProvider" --tag=apidoc-config

File config của package sẽ nằm ở Hanoisoundstuff.com lệnh sau để tạo API docs

php artisan apidoc:generate

Như vậy là chúng ta vừa tạo API docs mặc định để có thể tùy biến và viết thêm chi tiết cho API docs chúng ta sẽ chỉnh sửa như sau

Cấu hình

File config của package sẽ nằm ở chúng tôi Giải thích về config này như sau :

type: Kiểu document, nếu chọn là static thì document sẽ là một file HTML nằm ở public/docs, nếu chọn laravel thì document sẽ là một file blade nằm trong resources/views/apidoc.

route: để cố định là laravel

base_url: base URL của API, mặc định là config(‘app.url’)

postman: cài đặt post man collection

enabled: mặc định là true. sẽ tạo ra postman collection

name: trên của collection

description: mô tả cho collection

strategies: các service để parse API docs

logo: logo của trang API docs, kích thước chuẩn là 230 x 52

default_group: group mặc định của các endpoint không có thuộc tính @group

example_languages: ngôn ngữ lập trình cho các ví dụ

fractal: tìm hiểu thêm tại: https://fractal.thephpleague.com

routes: gồm nhiều nhóm để cài đặt cho API documents

Viết Document API

Để viết API document, bạn vào method trong controller mà route cần viết document trỏ tới. Và viết bên trên method đó như phần dưới mình viết document cho method index của trang list user:

Dòng đầu tiên là tên của API . Ở đây là api/users

Các dòng tiếp theo là mô tả param, response,message…

Kết quả

All Rights Reserved

--- Bài cũ hơn ---

Tôi Đã Viết Api Document Cho Dự Án Như Thế Nào?

Cách Viết Rails Api Document

Giới Thiệu Tool Swagger Ui

Học Kiểm Thử Api Trong 10 Phút

Cách Tạo Api Với Rails (Phần 2) Viết Test Case

--- Bài mới hơn ---

Hướng Dẫn Viết Game Design Document Dành Cho Người Mới

Cách Tôi Viết Document Cho React Component

Cách Viết Một Game Design Document Tốt

Hướng Dẫn Cách Ghi Tài Liệu Tham Khảo

Cách Trích Dẫn Tài Liệu Tham Khảo, Trình Bày Trích Dẫn Trong Bài Luận

Chào mọi người, bài viết này mình sẽ hướng dẫn các bạn làm thế nào để chạy và test một document API được viết bằng Swagger. Ở đây mình không đề cập đến các khái niệm, cú pháp và cách viết một file document API sử dụng Swagger, những thứ đó các ban có thể tham khảo ở trang chủ của Swagger chúng tôi mà chỉ đề cập cách để config swaagger làm thế nào để chạy trong dự án mà bạn đang làm mà thôi.

Hạn chế của các gem swagger trong Rails

class Api::V1::UsersController < ApplicationController swagger_controller :users, "User Management" swagger_api :index do summary "Fetches all User items" notes "This lists all the active users" param :query, :page, :integer, :optional, "Page number" param :path, :nested_id, :integer, :optional, "Team Id" response :unauthorized response :not_acceptable, "The request you made is not acceptable" response :requested_range_not_satisfiable end .........

Mặc dù nó không ảnh hưởng gì đến quá trình hoạt động của API, tuy nhiên nó gây khó chịu cho việc đọc code và việc nhúng vào file controller như thế này quả là không hay tí nào, vả lại nó cũng không hoàn toàn tuân theo cách viết document trên trang chủ của Swagger, nên đôi khí sẽ khó để config cho lập trình viên. Và thế là mình suy nghĩ làm cách nào để nhùng trực tiếp thư viện của thằng Swagger vào project của mình hay không ? Sau một hồi tìm hiểu thì Ơ rê ka ra rồi, và đôi khi nó đơn giản đến không ngời.

Option 1: Import thư viện Swagger UI

Thực chất thì để hiển thị một document API cho người dùng đọc, thì chỉ cần 2 thứ, đó là thư viện Swagger UI và file document API được viết theo cú pháp và cấu trúc của Swagger có định dạng là *.yaml. Để cài đặt nó trong project của mình thì bạn làm như sau:

Thực hiện pull thư viện swagger-ui từ trang github của nó vào project của mình như sau:

git clone [email protected]:swagger-api/swagger-ui.git public/swagger-ui

Sau đó config trong file config/routes.rb để Rails có thể nhận đường dẫn đến file html tĩnh để chạy màn hình document API:

get '/swagger-ui', to: redirect('swagger-ui/dist/index.html?url=%2Fswagger.yaml')

Và file document API mẫu của minhf là chúng tôi có nội dung như sau:

swagger: 2.0 info: description: Example of integration swagger with Rails version: 1.0.0 title: Rails 5 Swagger schemes: - http host: "localhost:3000" basePath: "/api/v1" paths: /users: post: tags: - Register user description: Create new user produces: - application/json parameters: - in: "formData" name: "user" required: true type: string - in: "formData" name: "user[avatar_id]" required: true type: number responses: 200: description: User created

Các bạn chú ý, như mình đã nói ở trên thì để chạy màn hình hiển thị document API của thằng swagger, thì ở đây mình đã pull thư viện swagger UI về project của mình và mình có file swagger.yaml, việc của mình chỉ là khai báo đường dẫn vào đến file chạy mà thôi.

Sau khi đã cài đặt xong, khởi động server Rails và truy cập vào đường dẫn: localhost:3000/swagger-ui, mình sẽ có kết quả như sau:

Hura, vậy là mình đã nhúng thành công nó, thấy có vể đơn giản quá nhỉ, và nó thực sự ok nếu các bạn không có yêu cầu gì thêm. Tuy nhiên vẫn có một vấn đề đặt ra ở giải pháp này đó là thư viện Swagger UI có dung lượng lên đến gần 200MB, và nó được push trực tiếp vào sourecode của dự án mình, thực sự thì k hay tí nào, và việc get đến url document API trực tiếp trên server API đang chạy cũng làm cho dễ bị lộ cấu trúc của API, vì thực chất thằng giao diện của Swagger UI là một file tĩnh và nó chỉ handle lại response trả về mà thôi. Hãy tương tượng nó như thằng Postman, tuy nhiên nó cung cấp thêm phần mô tả cho API mà thôi.

Option 2: Swagger with Docker

Như đã nói ở trên, để chạy swagger thì chỉ cần thư viện swagger-ui và file document API. Và ở đây mình muốn chạy server document API riêng với server API của mình. May thay Swagger đã support tận răng cho người dùng một image để chạy trên docker mà không cần phải config gì. Các bước thực hiện nó như sau:

Step 1: Cài đặt Docker.

Step 2: Sau khi cài đặt docker thì các bạn tiến hành pull image của swagger ui về bằng cách sử dụng command sau:

docker pull swaggerapi/swagger-ui

Step 3: Convert file *.yaml thành *.json

Step 4: Sau đó chạy command sau để khởi chạy server swagger

docker run -p 80:8080 -e "SWAGGER_JSON=/api.json" -v chúng tôi swaggerapi/swagger-ui

Step 5: Config CORS cho rails server API. Phương pháp này có một hạn chế đó là giữa 2 server phải giao tiếp với nhau. Vì vậy chúng ta phải config rack cors cho rails API. Ở đây mình sử dụng gem rack-cors, 1 gem thông dụng cho việc setting này.

Các bạn có thể tham khảo cách config ở trang github của nó: rack-cors gem.

Step 6: Khởi động server API và kiếm tra thành quả của mình thôi.

Option 3: Take it easy

Ở hai option trên, thì mình đã cung cấp cho các bạn cách làm thế nào để hiển thị một document viết bằng swagger, tuy nhiên, giả sử mình chỉ có một dự án nhỏ, API không nhiều lắm, có cần phải tốn công tải nguyên cả thư viện về hoặc phải cài docker để build hay không, giống như dùng dao mổ trâu mà giết gà vậy ? Sau khi vọc thư viện của nó thì mình nhận ra thằng swagger UI thì khi chạy, nó sẽ tìm đến file chúng tôi trong thư mục dist của thư viện.

Nếu để ý thì các bạn có thể nhận ra rằng để hiển thị một document đơn giản thật ra k cần nhiều lắm, 1 file css có tên là chúng tôi 2 file js là chúng tôi chúng tôi Uhm, vậy mấy thư viện css và js đó lấy đâu ra, tất nhiên là nó nằm ở cùng thư mục với file chúng tôi rồi, tuy nhiên, có cách nào đơn giản hơn nữa không ??? Search google 1 xí là ra ngay ấy mà, phải nói là thằng swagger này đã support tận răng cho dev, mình lên cdn search cái là ra liền à.

Và ở đây bạn chỉ cần thay attribute src của thẻ script và thẻ style thằng những link thư viện online tương ứng mà thôi. Vậy còn file document thì sao, đọc kĩ 1 tí thì bạn sẽ thấy dòng này.

url: "http://petstore.swagger.io/v2/swagger.json",

Thực ra đường dẫn này swagger cung cấp cho mình đến file document mẫu mà swagger cung cấp. Vì thế, để chạy document của riêng mình, thì chỉ cần parse file document API của chúng ta, up lên một server online nào đó và thay thế đường dẫn trên bằng đường dẫn đến file json của mình thôi. Ví dụ như file mình đã chỉnh sửa như sau:

Như vậy, với cách này, chúng ta chỉ cần duy nhất 1 file tĩnh chúng tôi theo mẫu của thằng swagger là đã hiển thị được document API rồi. Cực kì đơn giản phải không.

Kết luận

Như vậy ở bài này mình đã hướng dẫn cho các bạn các cách làm thế nào để config swagger để hiển thị document API. Tùy từng trường hợp và yêu cầu của mỗi người để chọn ra option phù hợp nhất, vì không có cái nào là tốt nhất cả. Ngoài thằng Swagger ra thì còn có thằng API Blueprint cũng được nhiều lập trình viên sử dụng. Hy vọng mình sẽ có điều kiện tìm hiểu và giới thiệu nó cho các bạn trong tương lai.

Cảm ơn các bạn đã theo dõi.

--- Bài cũ hơn ---

Cách Viết Specs Document Cơ Bản Và 7 Technique Để Viết Document Rõ Ràng, Dễ Hiểu

Hướng Dẫn Viết Có Dấu Trong Lol Đảm Bảo Thành Công 100%

Cách Đổi Tên Liên Minh Huyền Thoại Có Dấu Nhanh Trong 1 Nốt Nhạc

Hướng Dẫn Nhanh Cách Viết Tiếng Việt Trong Lol Ai Cũng Làm Được

Hướng Dẫn Cách Gõ Bàn Phím Có Dấu Nhanh, Đơn Giản

--- Bài mới hơn ---

Viết Api Document Cho Dự Án Sử Dụng Laravel

Tạo Ứng Dụng Android Đơn Giản Đưa Lên Google Play Trong 10 Tiếng

Cách Tạo Ứng Dụng Android / Ios Không Cần Biết Lập Trình

Appendix: Cách Tiếp Cận Trung Tâm

Appendix: Cách Tiếp Cận Kiểm Soát Dịch Vụ

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.

• 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:

  composer required mpociot/laravel-apidoc-generator

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

  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

  php artisan vendor:publish --provider= "MpociotApiDocApiDocGeneratorServiceProvider" --tag=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.

  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

  php artisan serve

  Ở 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?

All Rights Reserved

--- Bài cũ hơn ---

Cách Viết Rails Api Document

Giới Thiệu Tool Swagger Ui

Học Kiểm Thử Api Trong 10 Phút

Cách Tạo Api Với Rails (Phần 2) Viết Test Case

How To Write Test Cases ( Hướng Dẫn Cách Viết Testcases)

--- Bài mới hơn ---

Hướng Dẫn Cách Ghi Tài Liệu Tham Khảo

Cách Trích Dẫn Tài Liệu Tham Khảo, Trình Bày Trích Dẫn Trong Bài Luận

Hướng Dẫn Cách Viết Email Cho Doanh Nghiệp Chuyên Nghiệp Nhất

Hướng Dẫn Cách Viết Email Và Gửi Mail Chuyên Nghiệp

Hướng Dẫn Viết Email Chuyên Nghiệp

• Các đối tượng quan tâm đến GDD:
• Game designer, tất nhiên rồi
• Programmer, cần để biết game mình sẽ code
• Artist, biết thế giới game, story và art style
• Producer, để lên kế hoạch và dự trù chi phí
• QA, để xây dựng test plan
• Các đối tượng khác, ví dụ nhà đầu tư cho dự án
• Trong cái đối tượng quan tâm đến GDD thì programmer được coi là đối tượng quan trọng nhất vì:
• Cần biết để chọn engine phù hợp
• Theo sát các design trong GDD, giảm lãng phí thời gian hỏi han, bàn bạc
• Idea thường là do GD khởi sướng, nên programmer cần phải nắm bắt được bằng GDD
• Một số programmer không chơi và không có thời gian tham khảo nhiều game

Bởi vậy, khi game design viết GDD, hãy hỏi xem programmer muốn gì và cần gì. Nếu họ nói cần bỏ 1 chức năng nào đó thì hãy cứ bỏ đi (nếu không quá quan trọng 😀 )

2. Ngắn Gọn

Thật ra rất khó để viết một GDD ngắn, ngắn ở đây nghĩa là:

• Dễ viết
• Dễ đọc
• Dễ cập nhập
• Dễ sử dụng
• Ít mâu thuẫn
• Đơn giản
• Không phình to lên
• Không để trống
• Không copy & paste (từ các document khác vào)
• Loại bỏ text thừa, lặp lại

Một trong những việc nên làm để đảm bảo GDD ngắn gọn đó là chia các phần thiết kế chuyên sâu thành một document khác, ví dụ UI, hệ thống chỉ số nhân vận, hệ thống chỉ số skill, hệ thống hội thoại… Lúc đó trong GDD, để nhắc đến phần đó bạn chỉ cần viết:

HUD cần phải sáng, là một pop-up giữa màn hình

Nên tránh những câu dài lê thê trong GDD, ví dụ: Anh là nhân vật chính đẹp trai, có sở trường cưỡi ngựa (bạc mã) bắn cung, văn võ song toàn, sống trong tòa lâu đài nguy nga tráng lệ màu hồng… Thì bạn có thể ghi ngắn gọn: Anh là nhân vật tài sắc vẹn toàn, lại còn giàu nữanhà đẹp,

Ngoài ra các bạn nên lưu ý là programmer luôn thích document dạng một loạt gạch đầu dòng, để họ tiện kiểm tra xem đã hoàn thành tính năng nào.

3. Prioritize (Đặt Thứ Tự Ưu Tiên)

Hãy đặt thứ tự ưu tiên cho các tính năng trong game của bạn và chia chúng thành các phase (giai đoạn). Đây cũng chính là thứ tự thực hiện của dự án. Ví dụ

Phase 1 (prototype): 1 character

• Vũ khí mặc định
• Không có túi đồ
• Không có skill
• Phase 2:
• Có thể thay đổi giữa 2 vũ kỹ
• Có 2 skill
• Di chuyển và xài skill được

Phase 3:

Bạn cũng nên lưu ý là mình sẽ đặt thứ tự ưu tiên xuyên suốt dự án, chứ không phải chỉ cho 1 tính năng.

• Screenshot của các game khác có chức năng tương tự
• Biểu đồ, flow
• Các text mẫu

5. Thảo Luận và Tôn Trọng

Theo quan điểm của tôi, ai cũng có thể đề xuất ý tưởng, tính năng, thậm chí là thiết kế màn chơi. Tuy nhiên các ý kiến không nên mâu thuẫn lẫn nhau. Khi có bất đồng ý kiến cho một tính năng nào đó, các thành viên nên ngồi lại bàn bạc trên nguyên tác: Nhìn nhận dưới góc độ end user, là người chơi.

Sau khi bàn bạc thì sẽ thống nhất lại ý kiến cuối cùng, thời gian bàn bạc thống nhất không nên quá dài sẽ lãng phí thời gian và chậm tiến độ dự án.

6. Đầu Tư Vào Định Dạng Document Nên sử dụng template của team

• Thay đổi font chữ cho phù hợp
• Ngắt bằng các đường kẻ ngang
• Sử dụng bullet list (như dòng tôi đang viết)
• Nhưng đừng lạm dụng format quá

7. Sử Dụng Thuật Ngữ Rõ Ràng Và Dễ Hiểu

• Đừng nghĩ rằng người đọc chắn chắn sẽ hiểu các thuật ngữ mà bạn dùng. Ví dụ: DPS, MMMORPG…
• Tránh dùng các thuật ngữ riêng của công ty bạn vì bạn có thể đưa GDD này cho người khác xem.
• Thuật ngữ mới thì phải được xử dụng nhất quán
• Có thể dùng chú thích

8. Rõ Ràng, Không Dư Thừa Và Phải Đúng Ngữ Pháp/Chính Tả

Như đã nói ở phần 2, bạn cần phải cẩn thận khi viết GDD để đảm bảo không bị trùng lắp thông tin, từ ngữ dễ hiểu và đúng ngữ pháp, chính tả. Các game designer của tôi vẫn rất thích xài tiếng Anh, dù công ty toàn người Việt Nam, để viết GĐ, một phần để không bị mai một tiếng Anh, phần nữa là nhiều từ ngữ rất khó dịch sang tiếng Việt.

Sử dụng các từ nhấn mạnh và tránh các từ như: có lẽ, có thể, hình như, chắc là… (ở tiếng Anh là các từ như may, maybe, could, might…)

Đăng bởi Kiều Tiên

Tags: Cách Viết Một Game Design Document, Cách Viết Một Game Design Document Tốt, Game, Game Design Document, Game Design Document là gì, Game Design Document tốt, lập trình, lập trình game

--- Bài cũ hơn ---

Cách Tôi Viết Document Cho React Component

Hướng Dẫn Viết Game Design Document Dành Cho Người Mới

Cấu Hình Swagger Ui Để Viết Document Cho Api

Cách Viết Specs Document Cơ Bản Và 7 Technique Để Viết Document Rõ Ràng, Dễ Hiểu

Hướng Dẫn Viết Có Dấu Trong Lol Đảm Bảo Thành Công 100%

--- Bài mới hơn ---

Cách Viết Một Game Design Document Tốt

Hướng Dẫn Cách Ghi Tài Liệu Tham Khảo

Cách Trích Dẫn Tài Liệu Tham Khảo, Trình Bày Trích Dẫn Trong Bài Luận

Hướng Dẫn Cách Viết Email Cho Doanh Nghiệp Chuyên Nghiệp Nhất

Hướng Dẫn Cách Viết Email Và Gửi Mail Chuyên Nghiệp

Yêu cầu:

• Đã có kiến thức cơ bản về reactjs.
• Đã có kiến thức cơ bản về webpack, babel (nếu bạn muốn custom được các config của một số thư viện cho phép)
• Môi trường mình sẽ demo:

Mục đích:

• Thực hiện để biết cách sử dụng.
• Khuyến khích thói quen viết document cho những gì mình code.
• Tự kiểm nghiệm ưu và nhược điểm để sử dụng sao cho phù hợp với từng quy mô dự án.

Những phần bỏ qua:

• Trong quá trình chúng ta thực hiện thì mình sẽ lượt bớt (không giải thích những thuật ngữ và các lệnh cơ bản).
• Phần cấu hình mình sẽ không mô tả chi tiết trong bài viết, các bạn có thể theo dõi thông qua repo.
• .etc

Thư viện

1. Storybook

Storybook is an open source tool for developing UI components in isolation for React, Vue, and Angular. It makes building stunning UIs organized and efficient.

Như mô tả ở trên thì thằng này có thể tích hợp với nhiều thư việc khác không chỉ React. Qúa ngon

Cài đặt các thư viện chính sau

yarn add react react-dom yarn add @babel/core babel-loader @storybook/react --dev

Các file

Sau khi cài các thư viện cần thiết, tiếp theo mình sẽ thêm script trong file package.json để chạy thằng storybook như sau

Cấu hình cho storybook

Mục đích để storybook duyệt qua thư mục ../components và tìm các file có regex tương ứng là /.stories.js$/, những file này sẽ được storybook coi là các module mà nó cần load lên UI của nó.

Tạo file ví dụ

Đơn giản là tạo các prop để style cho Button component

Storybook component components/Button/index.stories.js

Cách viết cũng khá đơn giản. vì cơ bản nó cũng trả về react component thôi

Chạy

yarn storybook

Hiển thị

Nhìn có vẻ xịn

2. Docz

It’s never been easier to document your things!

Xây dựng dựa trên 4 nguyên tắc sau:

1. Zero config and easy to learn.
2. Blazing fast.
3. Easy to customize.
4. MDX based.

Thằng này khá mới, giao diện khi run app được xây dựng bằng gastsby và cũng sịn sò không kém.

Cài đặt các thư viện chính sau

yarn add react react-dom docz Mình sẽ demo thêm phần Props nên cần cài đặt thêm yarn add prop-types

Mình sẽ thêm script trong file package.json để chạy thằng docz như sau

package.json

Cấu hình cho docz

Mình sẽ điều chỉnh một vài cấu hình cho nó, những phần khác nó sẽ dùng cấu hình mặc định của docz. doczrc.js

Tạo file ví dụ

Tạo component components/Button/index.js

Mình vẫn sử dụng component ở ví dụ trên nhưng thêm phần PropTypes cho nó.

File document components/Button/index.mdx

Nhìn có vẻ gọn gàng, chuyên nghiệp nhỉ

Chạy

Hiển thị

Ngon không kém Storybook

Đó là những gì mình muốn chia sẽ hôm nay, tuy đơn giản nhưng lại vô cùng sâu sắc, hehe.

Cảm ơn mọi người đã đọc bài viết này.

--- Bài cũ hơn ---

Hướng Dẫn Viết Game Design Document Dành Cho Người Mới

Cấu Hình Swagger Ui Để Viết Document Cho Api

Cách Viết Specs Document Cơ Bản Và 7 Technique Để Viết Document Rõ Ràng, Dễ Hiểu

Hướng Dẫn Viết Có Dấu Trong Lol Đảm Bảo Thành Công 100%

Cách Đổi Tên Liên Minh Huyền Thoại Có Dấu Nhanh Trong 1 Nốt Nhạc

--- Bài mới hơn ---

Cấu Hình Swagger Ui Để Viết Document Cho Api

Hướng Dẫn Viết Game Design Document Dành Cho Người Mới

Cách Tôi Viết Document Cho React Component

Cách Viết Một Game Design Document Tốt

Hướng Dẫn Cách Ghi Tài Liệu Tham Khảo

Nguồn bài viết : サンプル例に見る機能仕様書の基本的な書き方＆読みやすくする7つのテクニック

Trong bài viết trước tác giả đã giải thích tầm quan trọng của document đối với communication trong dự án phát triển hệ thống IT, trong đó đã giới thiệu về 1 trong 3 loại document quan trọng là “Functional Specifications của Joel”. Trong bài viết này tác giả sẽ giải thích cụ thể về cách viết loại document này.

“Functional Specifications của Joel” là loại Specifications document về các màn hình và thao tác sử dụng software dựa trên quan điểm người dùng, là loại document chia sẻ thông tin giữa người dùng và người phát triển hệ thống. Vì không phải là document dành cho engineer nên tránh dùng nhiều từ ngữ chuyên ngành kĩ thuật khó hiểu.

Document gồm các mục sau

『Mở đầu』

Mục này sẽ viết vị trí các phần trong document và các lưu ý đối với người đọc khi đọc document. Ví dụ như trong document của Joel, ông viết là “Đây không phải là một document hoàn thiện”, nghĩa là document giống như 1 vật thể sống, sau này sẽ còn được cập nhật nhiều lần. Viết như thế này sẽ giúp người đọc tránh được hiểu lầm rằng đây là 1 document đã hoàn thiện không có sửa đổi gì nữa. Ngoài ra cũng có thể viết về mục đích của hệ thống, suy nghĩ nhắn nhủ với engineer…

『Scenario』

Để biết được hình ảnh của hệ thống khi thực tế sử dụng sẽ như thế nào thì cần viết scenario (story) theo cách nhìn của người dùng.

・Scenario là gì？

Scenario là văn bản viết các sự việc xảy ra theo mốc thời gian đúng theo trình tự triển khai của story. Những nhân vật sẽ xuất hiện và hành động của nhân vật đó, cùng với kết quả xử lí trả lại từ hệ thống được viết theo trình tự diễn ra 1 cách cụ thể.

・Cách viết scenario

Để người đọc không bị hiểu nhầm thì cần viết càng cụ thể càng tốt về tình huống sử dụng 1 cách dễ hiểu, ví dụ như đặt tên cho nhân vật, địa điểm sẽ xuất hiện.

Trường hợp nội dung quá phức tạp không thể viết hết trong 1 scenario thì nên chia ra theo đơn vị chức năng hoặc đơn vị màn hình, điều chỉnh cho phù hợp với từng hệ thống.

『Đối tượng ngoài』（hoặc là phạm vi ngoài）

Phần này sẽ viết những đối tượng ngoài phạm vi xử lí của hệ thống. Theo một ý nghĩa nào đó thì đây có lẽ là 1 trong những quan trọng nhất.

Trong quá trình làm dự án, khi phát hiện ra chức năng không có ghi trong document thì sẽ xảy ra 2 cách giải thích như sau:

1. Đây là chức năng cần thiết phải làm mà quên không viết vào document
2. Nếu không viết trong document thì chắc chắn là chức năng không cần làm

Trong hầu hết các trường hợp, 2 cách lý giải này sẽ gây ra hiểu nhầm , thường phía người dùng sẽ lý giải theo cách 1 còn team phát triển sẽ lý giải theo cách 2.

Để tránh gây ra hiểu nhầm như thế này thì nên viết những chức năng không làm vào mục “đối tượng ngoài” ở ngay phần đầu của document nơi dễ nhận thấy.

『Flow chart khái quát』（hoặc là Overview）

Đây sẽ là mục giải thích khái quát toàn bộ hình ảnh các chức năng của hệ thống trước khi đi vào các chức năng cụ thể. Có thể viết dạng flow chart hoặc bất cứ dạng nào khái quát được tổng thể toàn thể hệ thống. Thường có những loại như sơ đồ di chuyển màn hình, bản đồ flow nghiệp vụ, bản đồ usecase, list các chức năng…

Tất nhiên nếu văn bản có thể giải thích được đầy đủ cụ thể thì cũng không có vấn đề, quan trọng là nhìn từ quan điểm của người dùng có dễ hiểu hay không.

『Specification theo từng màn hình』（Specification chi tiết）

Phần này sẽ giải thích chi tiết các chức năng đã giải thích cơ bản ở phần “Khái quát”, là phần quan trọng nhất của 1 specification document.

Cần chú ý viết đủ, không sót các mục trong phạm vi đã nêu ra ở phần khái quát. Để làm được điều này cần phải chia mục 1 cách đầy đủ và hợp lí.

Màn hình có thể thực tế nhìn thấy nên là 1 đơn vị chia dễ hiểu và khó có thiếu sót. Ngoài ra còn có cách chia theo đơn vị chức năng , theo đơn vị input, output dữ liệu…

・Đặt tên cho các mục đã chia chi tiết

Khi đã chia các mục chi tiết rồi thì cần đặt tên cho chúng, nhằm giúp bất kì ai khi đọc document đều không bị hiểu nhầm mà có thể hiểu ngay được. Ví dụ như màn hình A, chức năng B, file C…đặt tên theo quy tắc cụ thể và ngắn gọn.

・Viết về các chức năng một cách cụ thể, chi tiết

Viết từng chức năng của hệ thống một cách cụ thể, chi tiết để người dùng có thể hiểu được. Bắt đầu từ chức năng cơ bản, rồi đến chức năng phụ trợ, hoạt động của màn hình, dữ liệu và file được export ra , các thao tác xảy khi có lỗi…nếu cần thiết sẽ có thêm các mục nhỏ trong từng chức năng.

Ở đây, quan điểm giải thích cũng là nhìn từ phía người dùng, xem người dùng nhìn hệ thống như thế nào rồi mới viết giải thích. Giải thích chi tiết này chính là điểm xuất phát quan trọng của document thực hiện, bởi trong quá trình thực hiện và test, để confirm mục đích và ý nghĩa của từng chức năng thì engineer cần xem lại document này rất nhiều lần.

『Những vấn đề chưa quyết định』（Hay To be determined – TBD）

Mục này sẽ viết những vấn đề hiện tại chưa thể giải quyết, quyết định được ngay, trong quá trình phát triển hệ thống rất hay nảy sinh ra những vấn đề như thế này. Để tránh việc bị thiếu trong quá trình viết thì khi nhận thấy vấn đề cần viết ngay lại chứ không chờ sau này mới tổng hợp lại.

『Technical memo』（Memo đặc biệt）

Phần này sẽ viết những ghi chú cho tầng độc giả đặc biệt. Người viết document hầu hết là người xuất thân từ ngành kĩ thuật. Document phải viết theo quan điểm của người dùng nhưng trong khi viết nhiều khi người viết nảy ra ý tưởng về cách giải quyết các vấn đề kĩ thuật. Nếu quên mất thì sẽ rất lãng phí nên cần tạo một mục gọi là “Technical memo” để ghi lại những ý tưởng như vậy.

【1】Viết câu ngắn gọn rõ ý

Viết từng câu càng ngắn càng tốt, nếu câu dài thì nên chia ra. Nên tránh cách viết mơ hồ, câu mang nhiều ý nghĩa, trong khả năng có thể viết câu ngắn gọn , ý nghĩa trọn vẹn trong 1 câu để người đọc dễ hiểu hơn.

Trong trường hợp nội dung nhiều không thể nói hết trong 1 câu thì dùng cách viết như “Nguyên tắc là…, tuy nhiên…”, đầu tiên nêu nội dung chủ đạo rồi sau đó thêm vào các trường hợp ngoại lệ, từ đó nêu rõ được ý muốn nói.

【2】Không tạo document template

Trong các doanh nghiệp hay tổ chức thường hay có những template cơ bản định hình các mục nên viết trong document, song điều này không được khuyến khích đối với người viết thông thường. Mỗi dự án phát triển lại có những nội dung, chức năng, quy mô, kiến trúc hệ thống khác nhau, từ đó mà những mục nên viết trong document cũng sẽ khác nhau. Vì vậy điều quan trọng là cần liệt kê được các mục cần có này khi thiết kế hệ thống.

Nếu cứ cố gắng tạo 1 template thì sẽ cần kết hợp các mục trong document của dự án 1 tỉ yen với dựa án 2 triệu yen, chỉ có cách đó mới tránh được việc thiếu sót khi liệt kê ra các mục cần thiết. Template cũng có thể tạo được, tuy nhiên chỉ giới hạn ở lĩnh vực và quy mô của đối tượng hệ thống cụ thể.

【3】『Tiêu đề, các đầu mục』chiếm 80% document

Để viết được document rành mạch dễ hiểu cần viết được nội dung 1 cách cụ thể, chi tiết, chia nhỏ các mục ra chứ không được viết gộp hết vào 1 mục. Chúng ta có thể sử dụng triệt để tiêu đề để làm được điều đó.

Tiêu đề chính là tên của 1 mục, có thể viết nội dung trước gắn tiêu đề sau, tuy nhiên nếu có thể thì nên xác định tiêu đề trước khi viết. Điều này sẽ giúp tránh được sai sót, giúp document rõ ràng dễ hiểu. Theo kinh nghiệm bản thân tác giả thì chỉ cần viết được hết ra các tiêu đề của đề mục là có cảm giác như đã hoàn thành 80% document rồi.

【4】Thứ tự các mục có thể quyết định sau

Ngay khi mới bắt đầu viết document thì sẽ có trường hợp chưa nhìn thấy được hình ảnh toàn cảnh, cấu trúc của document nên khi đó chưa cần quan tâm đến thứ tự các mục mà cứ viết hết ra những mục được cho là cần thiết. Sau đó đến 1 thời điểm nhất định sẽ nhìn ra được mối quan hệ giữa các mục, khi đó sắp xếp thứ tự cho chúng cũng chưa muộn.

【5】Những vấn đề chưa được quyết định gây băn khoăn

Nếu trong khi viết có những vấn đề chưa rõ ràng, chưa được quyết định thì cũng không nên băn khoăn mà dừng lại, chỉ cần đánh dấu chúng là “TBD – To be determined” là được. Những vấn đề này sẽ được giải quyết ở những cuộc họp hoặc điều tra, nghiên cứu riêng, khi đã được giải quyết rồi thì sẽ cập nhật lại document.

【6】Đùa vui trong chừng mực

Đặc biệt trong khi viết scenario thì để cho dễ hiểu và việc đọc trở nên thú vị hơn thì có thể sử dụng những câu đùa, tuy nhiên nên ở trong chừng mực và khi viết thì nên xem xét đối tượng đọc là ai.

Trong document của Joel có xuất hiện những câu đùa mà chỉ riêng những người trong một tổ chức mới hiểu được, song về cơ bản ở các document thì nên sử dụng ngôn ngữ formal tránh gây cảm giác là 1 tác phẩm mang xu hướng cá nhân hay thương hiệu riêng của cá nhân.

【7】Thường xuyên giữ cho document là 1 “thực thể sống”

Trong quá trình phát triển dự án người chịu trách nhiệm viết document cần phải thường xuyên cập nhật những thay đổi về chức năng, về những yêu cầu mới quyết định…điều này đồng thời tạo nên thành công cho document và cả dự án. Bởi như đã nói ở phía trên, việc này mang lại lợi ích trong nghiệp vụ phát triển dự án và tránh được những rủi ro không đáng có.

1. Dễ dàng tạo được những đoạn văn bản có tiêu đề
2. Dễ dàng chia sẻ được phiên bản online mới nhất 1 cách thường xuyên
3. Có thể thêm vào bảng hay biểu đồ.
4. Có thể xác định được lịch sử thay đổi cũng như các nội dung đã thay đổi

Những tool mà tác giả hay sử dụng

* A. Google document＋「Table of contents」add-on

* B. Microsoft Word

* C. Markdown text＋Subversion（hoặc là Git）

Đầu tiên là các tool tạo slide giống như Microsoft PowerPoint, bởi các slide tạo cảm giác mỗi slide là một đơn vị thông tin, nên sẽ không thể hiện được tính logic toàn bộ của document.

Ngoài ra với cùng lý do kể trên thì những tool như Microsoft Excel cũng nên tránh bởi chúng chia đơn vị theo sheet, theo cell gây khó khan trong việc thay đổi, sửa chữa vì document thường đi theo một mạch liên kết toàn thể.

Ai là người nên viết document

Theo Joel thì người nên viết document là program manager, người này sẽ đứng giữa team phát triển và người dùng để quyết định, điều chỉnh specification cho phù hợp.

Điều kiện của người viết document

1. Có thể viết được văn bản rõ ràng rành mạch, logic
2. Có thể đối thoại với người dùng và hiểu được người dùng
3. Xuất thân là nguời làm kĩ thuật hoặc có được kiến thức kĩ thuật trong 1 lĩnh vực cụ thể

   • Không viết document không thể hiện thực hóa trên phương diện kĩ thuật

   • Có thể đối thoại với team phát triển

   • Không nhất thiết cần là 1 programmer giỏi

4. Ít nhất cần có kiến thức cơ bản về thiết kế UI/UX
5. (Trường hợp phát triển sản phẩm của công ty) Cần có hiểu biết về đối tượng thị trường của sản phẩm 　Khó ai có thể đáp ứng được tất cả những yêu cầu kể trên, song ít nhất thì cũng cần phải viết được văn bản rõ ràng dễ hiểu hợp logic

Trong bài viết lần này tác giả đã giải thích cụ thể cách viết document theo phong cách của Joel, làm giảm communication lost giữa người dùng và team phát triển, từ đó tăng năng suất cho toàn dự án.

All Rights Reserved

--- Bài cũ hơn ---

Hướng Dẫn Viết Có Dấu Trong Lol Đảm Bảo Thành Công 100%

Cách Đổi Tên Liên Minh Huyền Thoại Có Dấu Nhanh Trong 1 Nốt Nhạc

Hướng Dẫn Nhanh Cách Viết Tiếng Việt Trong Lol Ai Cũng Làm Được

Hướng Dẫn Cách Gõ Bàn Phím Có Dấu Nhanh, Đơn Giản

Hướng Dẫn Cách Gõ Tiếng Việt Telex, Vni Có Dấu Trên Máy Tính Laptop

--- Bài mới hơn ---

Bài 68: Xây Dựng Web Service Dùng Api Restful Service(Phần 1)

Tạo Một Restful Api Đơn Giản Với Php Và Mysql

Hướng Dẫn Xây Dựng Web Api Entity Framework 2022

Hướng Dẫn Cách Tạo App Mobile Trong 10 Phút Đơn Giản Nhất

Hướng Dẫn Cách Tính Ngân Sách Phát Triển Cho Từng Loại Ứng Dụng

Có thể nói nguyên lí và cấu trúc dữ liệu RESTful được biết đến rộng rãi trong giới lập trình web nói chung và lập trình ứng dụng nói riêng.

Có thể nói bản thân REST không phải là một loại công nghệ. Nó là phương thức tạo API với nguyên lý tổ chức nhất định. Những nguyên lý này nhằm hướng dẫn lập trình viên tạo môi trường xử lý API request được toàn diện.

Để hiểu rõ hơn về RESTful API ta sẽ đi lần lượt giải thích các khái niệm API, REST hay RESTful.

RESTful API là một tiêu chuẩn dùng trong việc thiết kế API cho các ứng dụng web (thiết kế Web services) để tiện cho việc quản lý các resource. Nó chú trọng vào tài nguyên hệ thống (tệp văn bản, ảnh, âm thanh, video, hoặc dữ liệu động…), bao gồm các trạng thái tài nguyên được định dạng và được truyền tải qua HTTP.

API ( Application Programming Interface) là một tập các quy tắc và cơ chế mà theo đó, một ứng dụng hay một thành phần sẽ tương tác với một ứng dụng hay thành phần khác. API có thể trả về dữ liệu mà bạn cần cho ứng dụng của mình ở những kiểu dữ liệu phổ biến như JSON hay XML.

REST ( REpsentational State T ransfer) là một dạng chuyển đổi cấu trúc dữ liệu, một kiểu kiến trúc để viết API. Nó sử dụng phương thức HTTP đơn giản để tạo cho giao tiếp giữa các máy. Vì vậy, thay vì sử dụng một URL cho việc xử lý một số thông tin người dùng, REST gửi một yêu cầu HTTP như GET, POST, DELETE, vv đến một URL để xử lý dữ liệu.

RESTful API là một tiêu chuẩn dùng trong việc thiết kế các API cho các ứng dụng web để quản lý các resource. RESTful là một trong những kiểu thiết kế API được sử dụng phổ biến ngày nay để cho các ứng dụng (web, mobile…) khác nhau giao tiếp với nhau.

Chức năng quan trọng nhất của REST là quy định cách sử dụng các HTTP method (như GET, POST, PUT, DELETE…) và cách định dạng các URL cho ứng dụng web để quản các resource. RESTful không quy định logic code ứng dụng và không giới hạn bởi ngôn ngữ lập trình ứng dụng, bất kỳ ngôn ngữ hoặc framework nào cũng có thể sử dụng để thiết kế một RESTful API.

RESTful hoạt động như thế nào?

• GET (SELECT): Trả về một Resource hoặc một danh sách Resource.
• POST (CREATE): Tạo mới một Resource.
• PUT (UPDATE): Cập nhật thông tin cho Resource.
• DELETE (DELETE): Xoá một Resource.

Những phương thức hay hoạt động này thường được gọi là CRUD tương ứng với Create, Read, Update, Delete – Tạo, Đọc, Sửa, Xóa.

Hiện tại đa số lập trình viên viết RESTful API giờ đây đều chọn JSON là format chính thức nhưng cũng có nhiều người chọn XML làm format, nói chung dùng thế nào cũng được miễn tiện và nhanh.

Authentication và dữ liệu trả về

RESTful API không sử dụng session và cookie, nó sử dụng một access_token với mỗi request. Dữ liệu trả về thường có cấu trúc như sau:

{ "data" : { "id": "1", "name": "TopDev" } }

Status code

Khi chúng ta request một API nào đó thường thì sẽ có vài status code để nhận biết sau:

• 200 OK – Trả về thành công cho những phương thức GET, PUT, PATCH hoặc DELETE.
• 201 Created – Trả về khi một Resouce vừa được tạo thành công.
• 204 No Content – Trả về khi Resource xoá thành công.
• 304 Not Modified – Client có thể sử dụng dữ liệu cache.
• 400 Bad Request – Request không hợp lệ
• 401 Unauthorized – Request cần có auth.
• 403 Forbidden – bị từ chối không cho phép.
• 404 Not Found – Không tìm thấy resource từ URI
• 405 Method Not Allowed – Phương thức không cho phép với user hiện tại.
• 410 Gone – Resource không còn tồn tại, Version cũ đã không còn hỗ trợ.
• 415 Unsupported Media Type – Không hỗ trợ kiểu Resource này.
• 422 Unprocessable Entity – Dữ liệu không được xác thực
• 429 Too Many Requests – Request bị từ chối do bị giới hạn

Nên sử dụng Version

Luôn sử dụng version để khi bạn cần nâng cấp API mà vẫn hỗ trợ các API cũ.

Xây dựng API với Laravel

Lấy việc xây dựng api trên Laravel để làm ví dụ, trước khi đi vào ta tổng quan về Http Request.

HTTP Request

HTTP request có tất cả 9 loại method , 2 loại được sử dụng phổ biến nhất là GET và POST

• GET: được sử dụng để lấy thông tin từ server theo URI đã cung cấp.
• HEAD: giống với GET nhưng response trả về không có body, chỉ có header.
• POST: gửi thông tin tới sever thông qua các biểu mẫu http.
• PUT: ghi đè tất cả thông tin của đối tượng với những gì được gửi lên.
• PATCH: ghi đè các thông tin được thay đổi của đối tượng.
• DELETE: xóa tài nguyên trên server.
• CONNECT: thiết lập một kết nối tới server theo URI.
• OPTIONS: mô tả các tùy chọn giao tiếp cho resource.
• TRACE: thực hiện một bài test loop – back theo đường dẫn đến resource.

RESTful Route

Viết Api thì sẽ khai báo router vào file routes/api.php thay vì sử dụng file routes/web.php. Các setting mặc cho file api.php trong laravel:

• Url: những route được khai báo trong file này mặc định có pfix url là api (ví dụ: topdev.vn/api/products)
• Middleware: mặc định sẽ được gán Middleware Group là api, trong file app/Http/Kernel sẽ thấy 2 middleware thuộc Middleware Group: api là throttle (giới hạn request / time) và bindings (model binding).

Có thể tùy chỉnh giá trị mặc định này trong method mapApiRoutes trong file app/Providers/RouteServiceProvider.php

Tạo các route để thực hiện các thao tác như CRUD (Create, Read, Update, Delete):

// Lấy list sản phẩm // Lấy detail sản phẩm theo id // Add sản phẩm // Update info sản phẩm theo id # Sử dụng put nếu update toàn bộ các field # Sử dụng patch nếu update 1 vài field // Xóa sản phẩm theo id

Mặc định route đã được gán middleware bindings, nếu muốn sử dụng model binding trong controller thì chúng ta sửa lại tham số trong route như sau:

Ngoài ra trong laravel cũng hỗ trợ chúng ta 1 cách khai báo ngắn gọn hơn:

//Nếu không muốn sử dụng toàn bộ method trong apiResource mọi người có thể chỉ định sử dụng 1 vài method bằng hàm only //Hoặc nếu muốn loại bỏ đi 1 số method không dùng thì có thể sử dụng hàm except

Resource Controllers

Tương ứng với các Route RESTful đã khai báo ở trên, đặc biệt nếu dùng method apiResource thì laravel cũng hỗ trợ các method xử lí tương ứng trong controller.

Để tạo ra Resource Controllers chúng ta chạy lệnh sau

php artisan make:controller Api/ProductController -api

File ProductController tạo ra sẽ như sau<?php namespace AppHttpControllersApi; use IlluminateHttpRequest; use AppHttpControllersController; class ProductController extends Controller { /** * Display a listing of the resource. * * @return IlluminateHttpResponse */ public function index() { // } /** * Store a newly created resource in storage. * * @param IlluminateHttpRequest $request * @return IlluminateHttpResponse */ public function store(Request $request) { // } /** * Display the specified resource. * * @param int $id * @return IlluminateHttpResponse */ public function show($id) { // } /** * Update the specified resource in storage. * * @param IlluminateHttpRequest $request * @param int $id * @return IlluminateHttpResponse */ public function update(Request $request, $id) { // } /** * Remove the specified resource from storage. * * @param int $id * @return IlluminateHttpResponse */ public function destroy($id) { // } }

Ngoài ra nếu muốn sử dụng model binding khi tạo Resource Controllers thì dùng lệnh bên dưới

php artisan make:controller Api/ProductController --api --model=Models/Product

File ProductController tạo ra sẽ như sau, chúng ta để ý tham số của các method show, update, destroy sẽ thay đổi 1 chút.

<?php namespace AppHttpControllersApi; use AppModelsProduct; use IlluminateHttpRequest; use AppHttpControllersController; class ProductController extends Controller { /** * Display a listing of the resource. * * @return IlluminateHttpResponse */ public function index() { // } /** * Store a newly created resource in storage. * * @param IlluminateHttpRequest $request * @return IlluminateHttpResponse */ public function store(Request $request) { // } /** * Display the specified resource. * * @param AppModelsProduct $product * @return IlluminateHttpResponse */ public function show(Product $product) { // } /** * Update the specified resource in storage. * * @param IlluminateHttpRequest $request * @param AppModelsProduct $product * @return IlluminateHttpResponse */ public function update(Request $request, Product $product) { // } /** * Remove the specified resource from storage. * * @param AppModelsProduct $product * @return IlluminateHttpResponse */ public function destroy(Product $product) { // } }

Demo 1 đoạn code đơn giản trong controller kết hợp với model binding và route apiResource khi xây dựng API:

<?php namespace AppHttpControllersApi; use AppHttpControllersController; use AppModelsProduct; use IlluminateHttpRequest; class ProductController extends Controller { /** * Display a listing of the resource. * */ public function index() { return Product::all(); } /** * Store a newly created resource in storage. * * @param Request $request */ public function store(Request $request) { } /** * Display the specified resource. * * @param Product $product * @return Product */ public function show(Product $product) { return $product; } /** * Update the specified resource in storage. * * @param Request $request * @param Product $product * @return bool */ public function update(Request $request, Product $product) { } /** * Remove the specified resource from storage. * * @param Product $product * @throws Exception */ public function destroy(Product $product) { } }

Mặc định khi sử dụng route apiResource thì dữ liệu trả về sẽ tự động được chuyển sang kiểu JSON và sẽ có status tương ứng nên chỉ cần return dữ liệu ra là được.

Còn nếu muốn tùy biến status trả về thì có thể tham khảo cách phía dưới có sử dụng class IlluminateHttpResponse để lấy status thay vì fix giá trị vào ví dụ như HTTP_OK tương ứng sẽ là 200

<?php namespace AppHttpControllers; use AppModelsProduct; use IlluminateHttpRequest; use IlluminateHttpResponse; class ProductController extends Controller { /** * Display a listing of the resource. * * @return IlluminateHttpJsonResponse */ public function index() { $products = Product::all(); } } Eloquent Resources

Khi xây dựng API, bạn có thể cần transform dữ liệu từ controller trước khi trả về cho người dùng ứng dụng của bạn, laravel cũng đã hỗ trợ điều này với Eloquent Resources

Để tạo ra 1 class chuyển đổi chúng ta chạy lệnh sau

php artisan make:resource Product

File app/Http/Resources/Product.php sẽ có nội dung như sau

<?php namespace AppHttpResources; use IlluminateHttpResourcesJsonJsonResource; class Product extends JsonResource { /** * Transform the resource into an array. * * @param IlluminateHttpRequest $request * @return array */ public function toArray($request) { return parent::toArray($request); } }

Mình sẽ tùy chỉnh dữ liệu trả về là chỉ có title và price

<?php namespace AppHttpResources; use IlluminateHttpResourcesJsonJsonResource; class Product extends JsonResource{ /** * Transform the resource into an array. * * @param IlluminateHttpRequest $request * @return array */ public function toArray($request){ return [ ]; } }

Ở controller thì mình sẽ sửa lại như sau

<?php namespace AppHttpControllersApi; use AppHttpControllersController; use AppModelsProduct; use IlluminateHttpRequest; use AppHttpResourcesProduct as ProductResource; class ProductController extends Controller{ /** * Display a listing of the resource. * */ public function index(){ $products = Product::all(); return ProductResource::collection($products); } /** * Store a newly created resource in storage. * * @param Request $request */ public function store(Request $request){ return new ProductResource($product); } /** * Display the specified resource. * * @param Product $product * @return Product */ public function show(Product $product){ return new ProductResource($product); } /** * Update the specified resource in storage. * * @param Request $request * @param Product $product * @return bool */ public function update(Request $request, Product $product){ } /** * Remove the specified resource from storage. * * @param Product $product * @throws Exception */ public function destroy(Product $product){ } }

Authorization

Hiện tại có 3 cơ chế Authorize chính:

Tùy thuộc vào service của bạn, mà hãy chọn loại Authorize có mức độ phù hợp, cố gắng giữ nó càng đơn giản càng tốt.

CORS Policy

Viết API thì cũng cần chú ý về CORS là gì?

API Document

API document là một phần tương tự như Unit Test vậy - lấy ngắn để nuôi dài.

• Mô tả đầy đủ về params request: gồm những params nào, datatype, require hay optional.
• Nên đưa ra các ví dụ về HTTP requests và responses với data chuẩn.
• Cập nhật Docs thường xuyên, để sát nhất với API có bất cứ thay đổi gì.
• Format, cú pháp cần phải nhất quán, mô tả rõ ràng, chính xác.

--- Bài cũ hơn ---

Một Vài Kinh Nghiệm Viết Api

Viết Api Đầu Tiên Của Bạn Bằngvà Express: Tìm Hiểu Về Rest Api

Restful Api Cho Người Bắt Đầu

Bài 1: Cách Tạo Ứng Dụng Web Api

Cách Viết Và Cấu Trúc Chi Tiết Một Bài Báo Khoa Học