openapi接口规范 examples
时间: 2023-12-09 17:06:08 浏览: 67
OpenAPI(前称Swagger)是一个用于设计、构建、文档化和使用 RESTful API 的开放源代码工具集。它使用 JSON 或 YAML 格式来描述 API,包括 API 的请求和响应参数、操作、身份验证等信息。以下是一个简单的 OpenAPI 规范示例:
```yaml
openapi: 3.0.0
info:
title: My API
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: Get a list of users
operationId: getUsers
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
post:
summary: Create a new user
operationId: createUser
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
id:
type: integer
name:
type: string
```
在这个示例中:
- `openapi` 指定了所使用的 OpenAPI 版本。
- `info` 包含了 API 的基本信息,如标题和版本号。
- `servers` 定义了 API 的 URL。
- `paths` 定义了 API 的所有路径和操作。在这个示例中,我们定义了一个 `/users` 路径,包含了 `get` 和 `post` 操作。
- `get` 操作定义了获取用户列表的方式。它有一个 `summary` 描述、一个 `operationId` 标识符和一个 `responses` 对象,其中包含了 HTTP 响应码和相应的响应体。
- `post` 操作定义了创建新用户的方式。它有一个 `summary` 描述、一个 `operationId` 标识符、一个 `requestBody` 对象,其中包含了请求体的参数和类型,以及一个 `responses` 对象,其中包含了 HTTP 响应码和相应的响应体。
当你使用 OpenAPI 规范设计和构建 API 时,你可以使用这个示例作为参考,定义你的 API 的所有路径、操作和参数。