Introduce Swagger and Swagger in Django

1. Swagger

2. 介紹
●
用 JSON/YAML 描述 API 規格
●
提供線上編輯器
●
大部分的編輯器 / 開發環境都有輔助的 Plugin 支援
●
生器可以 生出各種語言的產 產 client library 以及
server stub 。
●
生器可以 生出漂亮的文件。產 產

7. CLI
●
除了可以用編輯器 生程式，也可以下指令產
● wget http://repo1.maven.org/maven2/io/swagger/swagger-codegen-
cli/2.2.0/swagger-codegen-cli-2.2.0.jar -O swagger-codegen-cli.jar
● photo_sharing.json 是編寫好的 swagger json 案檔
●
生給產 android 用的 library: java -jar swagger-codegen-cli.jar generate -l android -i
photo_sharing.json -o photo_sharing_android_client_lib
●
生產 angular2 用的 library: java -jar swagger-codegen-cli.jar generate -l
typescript-angular2 -i photo_sharing.json -o photo_sharing_angular_client_lib
●
生產 HTML 文件： java -jar swagger-codegen-cli.jar generate -l html -i
photo_sharing.json -o photo_sharing_html

8. django
●
與 django 結合應該 是跟說 django rest framework 結合
●
文件： https://django-rest-swagger.readthedocs.io/en/latest/
●
安裝：
– pip install django-rest-swagger
– settings.py 裡的 INSTALLED_APPS 加上 'rest_framework_swagger'
– urls.py 加入 get_swagger_view 的相關程式

12. ●
注意事項
– django-rest-swagger 是根據 django rest framework
產生 swagger 的介面與 json/yaml ，而不是從
json/yaml 產生出 server stub 程式
– swagger 產生器沒有 django 的產生器 :(

13. 怎麼寫 - JSON
●
基本架構： info 與 paths
{
"swagger": "2.0",
"info": {
"description": "",
"version": "1.0.0",
"title": "API prototype",
"contact": {
"email": "anonymous@gmail.com"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"paths": {
}
}

14. 怎麼寫 - JSON
●
paths 是一個 dictionary ， key 表示 path ， value 裡則描述
method 。 method 裡再描述參數等資訊。{
"/pet": {
"get": {
"tags": ["pet"],
"summary": "Get pets to the store",
"description": "",
"operationId": "getPets",
"parameters": [],
"responses": {
"405": {
"description": "Invalid input"
}
}
}
}
}

15. 怎麼寫 - YAML
●
基本架構： info 與 paths
---
swagger: "2.0"
info:
description: ""
version: "0.0.1"
title: "Example"
contact:
email: "anonymous@gmail.com"
license:
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
paths: {}

16. 怎麼寫 - YAML
●
跟 JSON 一樣， paths 是 dictionary， value 裡則描述 method； method 裡再描述其他
資訊
/pet:
post:
tags:
- "pet"
summary: "Add a new pet to the store"
description: ""
operationId: "addPet"
consumes:
- "application/json"
- "application/xml"
parameters: []
responses:
405:
description: "Invalid input"

17. swagger 規格定義
● http://swagger.io/specification/

18. Q&A