OpenAPI文件的簡單範例如下。
下面撰寫了兩個API路徑:
GET|/employee/{id}
:查詢員工POST|/employee
:新增員工
demo.yaml
openapi: 3.0.0
info:
contact:
name: "菜鳥工程師肉豬"
url: "https://matthung0807.blogspot.com/"
title: "OpenAPI Demo"
version: "1.0.0"
servers:
- url: http://localhost:8080
description: local
- url: http://abc.com:8080
description: dev
paths:
"/employee/{id}":
get:
description: Query a employee by ID
parameters:
- description: Employee ID
in: path
name: id
required: true
schema:
type: integer
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/Employee"
"204":
description: No conetnt
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
tags:
- Employee
"/employee":
post:
description: Creates a employee.
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Employee"
description: Employee data
required: true
responses:
"201":
description: Success
content:
text/plain:
schema:
type: integer
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
tags:
- Employee
components:
schemas:
Employee:
type: object
required:
- name
- age
properties:
id:
type: integer
name:
type: string
age:
type: integer
department:
$ref: '#/components/schemas/Department'
Department:
type: object
properties:
departmentId:
type: string
manager:
type: string
ErrorResponse:
type: object
properties:
error:
type: string
code:
type: string
將內容貼到Swagger Editor可產生相應的Swagger UI頁面。
沒有留言:
張貼留言