Django drf 概要和客戶端庫
概要是一種機(jī)器可讀文檔，用于描述可用的API路徑，其URLS以及它們支持的操作。
概要可以是自動(dòng)生成文檔的有用工具，也可以用于驅(qū)動(dòng)可以與API進(jìn)行交互的動(dòng)態(tài)客戶端庫。
Core API
為了提供概要支持REST框架使用Core API。
Core API是用于描述API的文檔規(guī)范。它用于提供可用路徑的內(nèi)部表示形式和API公開的可能的交互。它可以用于服務(wù)器端或客戶端。
當(dāng)使用服務(wù)器端時(shí)，coreAPI允許API支持呈現(xiàn)范圍廣泛的概要或超媒體格式。
當(dāng)使用客戶端時(shí)，核心API允許動(dòng)態(tài)驅(qū)動(dòng)的客戶端庫，它可以與任何公開受支持的概要或超媒體格式的API交互。
添加概要
REST框架支持明確定義的概要視圖或自動(dòng)生成的概要。由于我們使用的是視圖集和路由器，我們可以簡(jiǎn)單地使用自動(dòng)概要生成。
你需要安裝coreapi python包才能包含API概要。
$ pip install coreapi現(xiàn)在我們可以通過在URL配置中包含一個(gè)自動(dòng)生成的概要視圖來為API添加概要。
from rest_framework.schemas import get_schema_view
schema_view = get_schema_view(title='Pastebin API')
urlpatterns = [
url('^schema/$', schema_view),
...
]如果你在瀏覽器中訪問API根路徑，那么你現(xiàn)在應(yīng)該可以看到corejson表示形式是一個(gè)可用選項(xiàng)。
我們也可以通過在Accept標(biāo)頭中指定所需的內(nèi)容類型從命令行請(qǐng)求概要。
$ http http://127.0.0.1:8000/schema/ Accept:application/coreapi+json
HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/coreapi+json
{
"_meta": {
"title": "Pastebin API"
},
"_type": "document",
...默認(rèn)輸出樣式是使用Core JSON編碼。
還支持其他概要格式，如Open API（以前叫Swagger）。
使用命令行客戶端
現(xiàn)在我們的API暴露了一個(gè)概要路徑，我們可以使用一個(gè)動(dòng)態(tài)的客戶端庫與API進(jìn)行交互。為了演示這個(gè)，我們來使用Core API命令行客戶端。
命令行客戶端作為一個(gè)coreapi-cli包提供：
$ pip install coreapi-cli現(xiàn)在檢查它在命令行上是否可用...
$ coreapi
Usage: coreapi [OPTIONS] COMMAND [ARGS]...
Command line client for interacting with CoreAPI services.
Visit http://www.coreapi.org for more information.
Options:
--version Display the package version number.
--help Show this message and exit.
Commands:
...首先，我們將使用命令行客戶端加載API概要。
$ coreapi get http://127.0.0.1:8000/schema/
<Pastebin API "http://127.0.0.1:8000/schema/">
snippets: {
highlight(id)
list()
read(id)
}
users: {
list()
read(id)
}我們還沒有認(rèn)證，所以現(xiàn)在我們只能看到只讀路徑，這與我們?cè)O(shè)置的API權(quán)限是一致的。
我們使用命令行客戶端，嘗試列出現(xiàn)有的代碼片段：
$ coreapi action snippets list
[
{
"url": "http://127.0.0.1:8000/snippets/1/",
"id": 1,
"highlight": "http://127.0.0.1:8000/snippets/1/highlight/",
"owner": "lucy",
"title": "Example",
"code": "print('hello, world!')",
"linenos": true,
"language": "python",
"style": "friendly"
},
...一些API路徑需要命名參數(shù)。例如，要獲取特定代碼片段的高亮HTML表示，我們需要提供一個(gè)id。
$ coreapi action snippets highlight --param id=1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Example</title>
...驗(yàn)證我們的客戶端
如果我們想要?jiǎng)?chuàng)建，編輯和刪除代碼片段，我們需要進(jìn)行有效性用戶身份驗(yàn)證。在這種情況下，我們只需使用基本的auth。
請(qǐng)確保使用實(shí)際的用戶名和密碼替換下面的<username>和<password>。
$ coreapi credentials add 127.0.0.1 <username>:<password> --auth basic
Added credentials
127.0.0.1 "Basic <...>"現(xiàn)在，如果我們?cè)俅翁崛「乓?，我們?yīng)該能夠看到一組可用的交互。
$ coreapi reload
Pastebin API "http://127.0.0.1:8000/schema/">
snippets: {
create(code, [title], [linenos], [language], [style])
delete(id)
highlight(id)
list()
partial_update(id, [title], [code], [linenos], [language], [style])
read(id)
update(id, code, [title], [linenos], [language], [style])
}
users: {
list()
read(id)
}我們現(xiàn)在能夠與這些路徑行交互。例如，要?jiǎng)?chuàng)建一個(gè)新的代碼片段:
$ coreapi action snippets create --param title="Example" --param code="print('hello, world')"
{
"url": "http://127.0.0.1:8000/snippets/7/",
"id": 7,
"highlight": "http://127.0.0.1:8000/snippets/7/highlight/",
"owner": "lucy",
"title": "Example",
"code": "print('hello, world')",
"linenos": false,
"language": "python",
"style": "friendly"
}然后刪除一個(gè)代碼片段：
$ coreapi action snippets delete --param id=7除了命令行客戶端，開發(fā)人員還可以使用客戶端庫與你的API進(jìn)行交互。Python客戶端庫是第一個(gè)可用的庫，并且計(jì)劃即將發(fā)布一個(gè)Javascript客戶端庫。
有關(guān)定制模式生成和使用Core API客戶端庫的更多詳細(xì)信息，您需要參考完整的文檔。
回顧我們所做的
使用非常少的代碼，我們現(xiàn)在有一個(gè)代碼收集系統(tǒng)的webAPI，它是完全的瀏覽器可瀏覽的，包括一個(gè)概要驅(qū)動(dòng)的客戶端庫和帶有身份驗(yàn)證、每個(gè)對(duì)象的權(quán)限控制和多個(gè)渲染器格式支持。
我們已經(jīng)走過了設(shè)計(jì)過程的每個(gè)步驟，并且看到如果我們需要自定義任何東西，我們都可以按部就班的簡(jiǎn)單地使用常規(guī)的Django視圖實(shí)現(xiàn)。
你可以查看GitHub上的最終教程代碼，或者嘗試下沙箱中的實(shí)例。
越來越成功
我們已經(jīng)完成了我們的教程。如果你想要更多地參與到REST框架項(xiàng)目中，以下是你可以開始的幾個(gè)地方：
- 通過審查和提交問題，并pull requests，為GitHub做出貢獻(xiàn)。
- 加入REST framework 討論組，并幫助構(gòu)建社區(qū)。
- 在Twitter成為作者的粉絲，并打個(gè)招呼。
現(xiàn)在就去構(gòu)建非常棒的東西吧。
更多建議：