Modern Web 2018
進階補充版本
by 劉艾霖
Outline
-
其他應用場景
-
Mise
-
2.0 ---> 3.0
-
其他同類型的產品
-
Demo
其他應用場景
舊專案
-
swagger decorator 自動轉出文件
-
透過 Swagger Inspector 匯出基礎版本的文件
export default class UserController {
@apiRequestMapping("get", "/user/:id")
@apiDescription("get user object by id, only access self or friends")
@pathParameter({
name: "id",
description: "user id",
type: "integer"
})
@queryParameter({
name: "tags",
description: "user tags, for filtering users",
required: false,
type: "array",
items: ["string"]
})
@apiResponse(200, "get user successfully", User)
static async getUserByID(ctx, next): User {
...
}
}
Demo
簡易查詢後台
- 測試寄信功能
- 重寄報表
- 查看狀態
Mise
/**
* Represents a book.
* @constructor
* @param {string} title - 標題
* @param {string} author - 作者
*/
function Book(title, author) {}
const Koa = require('koa');
const koaSwagger = require('koa2-swagger-ui');
const app = new Koa();
app.use(
koaSwagger({
routePrefix: '/docs',
swaggerOptions: {
url: 'http://petstore.swagger.io/v2/swagger.json',
},
}),
);
var fs = require('fs');
var CodeGen = require('swagger-js-codegen').CodeGen;
var file = 'swagger/spec.json';
var swagger = JSON.parse(fs.readFileSync(file, 'UTF-8'));
var nodejsSourceCode = CodeGen.getNodeCode({ className: 'Test', swagger: swagger });
var angularjsSourceCode = CodeGen.getAngularCode({ className: 'Test', swagger: swagger });
var reactjsSourceCode = CodeGen.getReactCode({ className: 'Test', swagger: swagger });
var source = CodeGen.getCustomCode({
moduleName: 'Test',
className: 'Test',
swagger: swaggerSpec,
template: {
class: fs.readFileSync('my-class.mustache', 'utf-8'),
method: fs.readFileSync('my-method.mustache', 'utf-8'),
type: fs.readFileSync('my-type.mustache', 'utf-8')
}
});
CORS
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();
});
2.0 ---> 3.0 更動的部分
Common Mark
-
Github Flavored Markdown (GFM) ---> Common Mark
parameters body
parameters:
- in: "body"
name: "body"
description: "新增 Pet object"
required: true
schema:
$ref: "#/definitions/Pet"
requestBody:
$ref: '#/components/requestBodies/Pet'
2.0
3.0
新增 Link Object
-
新增 Link 類似 HATEOAS
Multiple Servers
servers:
- url: https://development.gigantic-server.com/v1
description: Development server
- url: https://staging.gigantic-server.com/v1
description: Staging server
- url: https://api.gigantic-server.com/v1
description: Production server
Multiple Servers
servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
description: The production API server
variables:
username:
# note! no enum here means it is an open value
default: demo
description: this value is assigned by the service provider.
port:
enum:
- '8443'
- '443'
default: '8443'
basePath:
# special base paths as assigned by the provider, default is `v2`
default: v2
more components
components: # 可以重複使用的元件
schemas: {}
parameters: {}
responses: {}
securitySchemes: {} # 認證 schemes
2.0 ---> 3.0 更動的部分
-
Github Flavored Markdown (GFM) ---> CommonMark
-
parameters body 被獨立成 requestBody
-
新增 Link 類似 HATEOAS
-
Multiple Servers
-
more components
https://github.com/Mermade/oas-kit
- OAS 3.0 白皮書
- 更完整的 OpenAPI 3.0 範例
其他同類型的產品
-
API Blueprint
-
基於 Markdown
-
-
Raml
-
Postman
-
apidoc
更多資源
Demo
https://github.com
/alincode/modern-web-2018-swagger
總結
Modern Web 2018 - 進階補充版本
By alincode
Modern Web 2018 - 進階補充版本
by alincode
- 1,307