一、openapi.yaml 代码示例:
openapi: 3.0.3
info:
title: Sample Pet Store App 2.0
description: |
This is a sample server for a pet store.
# Test technologies
- Test 1
- Test 2
- Test 3
# Important
HTTPS only. RESTful, resource oriented
# Get Started
Set up your APIs or get authorization
# Request and Response
application/json
# Support
[Sandbox Hub](https://test.com/sandbox)
termsOfService: 'http://example.com/terms/'
license:
name: Apache 2.0
url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
version: 1.0.0
servers:
- url: 'https://development.gigantic-server.com/v1'
description: Development server
- url: 'https://dev.test.com/v2'
description: Development environment
tags:
- name: pet
description: Pets operations.
- name: Accounts
description: Operations related to user's account info.
paths:
/wallets:
post:
tags:
- Wallets
operationId: create_wallet
summary: Create new wallet
description: ..More detailed explanation on creating a new wallet..
security:
- OAuth2:
- 'wallets:write'
- admin
- CoboAuth: []
CoboSignature: []
CoboNonce: []
- CookieAuth: []
parameters:
- $ref: '#/components/parameters/orgIdQueryParam'
requestBody:
$ref: '#/components/requestBodies/createWalletBody'
responses:
'201':
$ref: '#/components/responses/createWalletResponse'
'400':
$ref: '#/components/responses/badRequestError'
get:
tags:
- Wallets
operationId: list_wallets
summary: List all wallets
description: Retrieve a list of wallets.
security:
- OAuth2:
- 'wallets:read'
- admin
- CoboAuth: []
CoboSignature: []
CoboNonce: []
- CookieAuth: []
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/filterByType'
- $ref: '#/components/parameters/orgIdQueryParam'
responses:
'200':
$ref: '#/components/responses/getWalletsApi'
二、字段释义
1. openapi:版本号,必选. 该
字段应该被工具或者客户端用来解释 OpenAPI 文档
2. info:提供API相关的元数据,必选
1) title: 应用的名称。必选.
2) description:对应用的简短描述
3) version:API文档的版本信息,必选.
3. servers:Server对象的数组, 提供到服务器的连接信息
4. tags:提供更多元数据的一系列标签
5. paths:对所提供的API有效的路径和操作。必选。
三、Paths对象
描述对路径的某个操作
1. tags:用于控制API文档的标签列表,标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件
2. operationId:用于标识此操作的唯一字符串,这个id在此API内包含的所有操作中必须是唯一的
3. summary:对此操作行为的简短描述
4. description:对此操作行为的详细解释
5. security:声明安全机制
6. parameters:定义可用于此操作的参数列表
7. requestBody:可用于此操作的请求体
8. responses:必选.定义执行此操作后的可能的响应值列表