swagger: '2.0'
info:
version: 1.0.0
title: test API
description: this is test
schemes:
- http
host: localhost:3000
basePath: /
paths:
其中最上面指的是使用swagger的版本，目前固定是2.0.0
中間部分等於是指定API server的位置，意思為http:localhost:3000/
再來我們會開始往paths裡面寫api
#寫paths的步驟
1.路徑 /test
2.動詞 get,post...
3.四劍客 summary description parameters responses
4.在parameters下寫參數
- name: pageSize
in: query
description: Number of persons returned
type: integer
5.在responses下寫response code 200,304...
6.每個response code下有回傳的東西
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
基本上我們寫這樣就夠了
GET 簡單範本
/getUser:
# This is a HTTP operation
get:
description: |
取得使用者，使用query方法
parameters:
- name: id
in: query
description: 使用者id
required: true
type: string
responses:
"200":
description: Success
GET 方法的完整範例
server.js
var express = require('express')
var app = express()
app.use('*', function(req, res, next) {
res.header('Access-Control-Allow-Origin', '*');
res.header('Access-Control-Allow-Methods', 'GET, PUT, POST, DELETE, OPTIONS');
res.header('Access-Control-Allow-Headers', 'Accept, Origin, Content-Type');
res.header('Access-Control-Allow-Credentials', 'true');
next();
});
app.get('/allArticle', function (req, res) {
res.json({
result: 'ok',
data: 'thisisall'
})
})
app.get('/getArticle/:id', function (req, res) {
console.log(req.params);
res.json({
result: 'ok',
data: ['data1','data2']
})
})
app.get('/getUser', function (req, res) {
console.log(req.query);
res.json({
result: 'ok',
data: ['data1','data2']
})
})
app.listen(3000, function () {
console.log('Example app listening on port 3000!')
})
yaml
swagger: '2.0'
host: localhost:3000
info:
version: "1.0.0"
title: <testAPI>
paths:
/allArticle:
# This is a HTTP operation
get:
# Describe this verb here. Note: you can use markdown
description: |
取得所有文章
responses:
"200":
description: Success
/getArticle/{id}:
# This is a HTTP operation
get:
# Describe this verb here. Note: you can use markdown
description: |
取得特定文章使用params方法
# This is array of GET operation parameters:
parameters:
- name: id
in: path
description: 文章id
required: true
type: string
responses:
"200":
description: Success
/getUser:
# This is a HTTP operation
get:
# Describe this verb here. Note: you can use markdown
description: |
取得使用者，使用query方法
# This is array of GET operation parameters:
parameters:
- name: id
in: query
description: 使用者id
required: true
type: string
responses:
"200":
description: Success
/register:
post:
description: add a new user
# movie info to be stored
consumes:
- application/x-www-form-urlencoded
parameters:
- name: account
description: 使用者帳號
type: string
in: formData
required: true
- name: password
description: 使用者密碼
type: string
in: formData
required: true
responses:
"200":
description: Success
server.js
var express = require('express');
var app = express();
var bodyParser = require('body-parser')
app.use(bodyParser());
app.use('*', function(req, res, next) {
res.header('Access-Control-Allow-Origin', '*');
res.header('Access-Control-Allow-Methods', 'GET, PUT, POST, DELETE, OPTIONS');
res.header('Access-Control-Allow-Headers', 'Accept, Origin, Content-Type');
res.header('Access-Control-Allow-Credentials', 'true');
next();
});
app.get('/allArticle', function (req, res) {
res.json({
result: 'ok',
data: 'thisisall'
})
})
app.get('/getArticle/:id', function (req, res) {
console.log(req.params);
res.json({
result: 'ok',
data: ['data1','data2']
})
})
app.get('/getUser', function (req, res) {
console.log(req.query);
res.json({
result: 'ok',
data: ['data1','data2']
})
})
app.post('/register',function (req,res) {
console.log(req.body);
res.json({
result: 'ok',
data: ['data1','data2']
})
})
app.listen(3000, function () {
console.log('Example app listening on port 3000!')
})
最後加上PUT與DELETE方法
server.js
var express = require('express');
var app = express();
var bodyParser = require('body-parser')
app.use(bodyParser());
app.use('*', function(req, res, next) {
res.header('Access-Control-Allow-Origin', '*');
res.header('Access-Control-Allow-Methods', 'GET, PUT, POST, DELETE, OPTIONS');
res.header('Access-Control-Allow-Headers', 'Accept, Origin, Content-Type');
res.header('Access-Control-Allow-Credentials', 'true');
next();
});
app.get('/allArticle', function (req, res) {
res.json({
result: 'ok',
data: 'thisisall'
})
})
app.get('/getArticle/:id', function (req, res) {
console.log(req.params);
res.json({
result: 'ok',
data: ['data1','data2']
})
})
app.get('/getUser', function (req, res) {
console.log(req.query);
res.json({
result: 'ok',
data: ['data1','data2']
})
})
app.post('/register',function (req,res) {
console.log(req.body);
res.json({
result: 'ok',
data: ['data1','data2']
})
})
app.put('/user', function (req, res) {
console.log(req.body);
console.log('user info updated!')
res.send('Got a PUT request at /user');
});
app.delete('/user', function (req, res) {
console.log(req.body);
console.log('user deleted!')
res.send('Got a DELETE request at /user');
});
app.listen(3000, function () {
console.log('Example app listening on port 3000!')
})
yaml
swagger: '2.0'
host: localhost:3000
# This is your document metadata
info:
version: "1.0.0"
title: <testAPI>
# Describe your paths here
paths:
/allArticle:
# This is a HTTP operation
get:
# Describe this verb here. Note: you can use markdown
description: |
取得所有文章
responses:
"200":
description: Success
/getArticle/{id}:
# This is a HTTP operation
get:
# Describe this verb here. Note: you can use markdown
description: |
取得特定文章使用params方法
# This is array of GET operation parameters:
parameters:
- name: id
in: path
description: 文章id
required: true
type: string
responses:
"200":
description: Success
/getUser:
# This is a HTTP operation
get:
# Describe this verb here. Note: you can use markdown
description: |
取得使用者，使用query方法
# This is array of GET operation parameters:
parameters:
- name: id
in: query
description: 使用者id
required: true
type: string
responses:
"200":
description: Success
/register:
post:
description: add a new user
# movie info to be stored
consumes:
- application/x-www-form-urlencoded
parameters:
- name: account
description: 使用者帳號
type: string
in: formData
required: true
- name: password
description: 使用者密碼
type: string
in: formData
required: true
responses:
"200":
description: Success
/user:
put:
description: 更新個人資料
# movie info to be stored
consumes:
- application/x-www-form-urlencoded
parameters:
- name: account
description: 使用者帳號
type: string
in: formData
required: true
- name: password
description: 使用者密碼
type: string
in: formData
required: true
- name: info
description: 個人資料
type: string
in: formData
required: true
responses:
"200":
description: Success
delete:
description: 刪除使用者
# movie info to be stored
consumes:
- application/x-www-form-urlencoded
parameters:
- name: account
description: 使用者帳號
type: string
in: formData
required: true
- name: password
description: 使用者密碼
type: string
in: formData
required: true
responses:
"200":
description: Success
response code 如果沒寫就看不到response
Request 參數
formData POST Data
path parameters, such as /users/{id}
query parameters, such as /users?role=admin
header parameters, such as X-MyHeader: Value
cookie parameters, which are passed in the Cookie header, such as Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU
Schema 型別
string (this includes dates and files)
number
integer
boolean
array
object
