OpenAPI Basic Structure
OpenAPI Basic Structure
- OpenAPI 版本
- 项目原信息
- servers
- paths
- parameters
- request body
- responses
- 输入输出模型: schemas
- Authentication
# 指定 openapi 版本 3.0.0
openapi: 3.0.0
# 你的 Api 的信息
info:
# 项目名称
title: Sample API
# 描述
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
# Api 项目版本
version: 0.1.9
# 你的 Api 项目的访问路径(可以指定多个)
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
description: Optional server description, e.g. Internal staging server for testing
# 你的 Api 接口
paths:
# 接口路径
/users:
# 请求方法 get/post ...
get:
# 简介
summary: Returns a list of users.
# 描述
description: Optional extended description in CommonMark or HTML.
# 返回
responses:
# 状态码
'200':
# 返回的描述
description: A JSON array of user names
# 返回 Content-Type: application/json
content:
application/json:
schema:
type: array
items:
type: string
/user/{userId}:
get:
summary: Returns a user by ID.
# 请求参数 userId, 是 路径上的请求参数, 必填, 整型, 最小值为1
parameters:
- name: userId
# 路径上的请求参数
in: path
# 必填
required: true
description: Parameter description in CommonMark or HTML.
# 整型, 最小值为1
schema:
type : integer
format: int64
minimum: 1
responses:
'200':
description: OK
/users/private:
post:
summary: Creates a user.
# 请求体
requestBody:
required: true
content:
# Content-Type: application/json
application/json:
# 请求体信息 定义
schema:
type: object
properties:
username:
type: string
responses:
'200':
description: A user object.
content:
application/json:
# 返回的模型
schema:
$ref: '#/components/schemas/User'
'400':
description: The specified user ID is invalid (not a number).
'404':
description: A user with the specified ID was not found.
default:
description: Unexpected error
# 指定这个接口使用 BasicAuth 授权
security:
- BasicAuth: []
components:
# 这是全局的模型, 可以被引用 $ref
schemas:
User:
# 模型中的属性
properties:
id:
type: integer
format: int64
# 返回示例 4
example: 4
name:
type: string
example: Jessica Smith
# Both properties are required
required:
- id
- name
# 定义授权
securitySchemes:
BasicAuth:
type: http
scheme: basic
本作品采用《CC 协议》,转载必须注明作者和本文链接
推荐文章: