简介
Swagger Specification(Swagger 规范),现在称作 OpenAPI Specification (OpenAPI 规范)。
OpenAPI 规范定义了如何去描述你的 API 信息。
OpenAPI 规范允许你以 json 或 yaml 的语法格式,来编写 Swagger 文件。
基本结构
在 Swagger 文件中,你可以使用 json 或 yaml 的语法,来描述你的 API 。
这里,我们以 yaml 为例,来介绍 Swagger 文档(文件)的基本结构。
下面是一个例子 demo.yaml。
openapi: 3.0.0
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
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
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
'200': # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string
注:所有的关键字都区分大小写。
Metadata(元数据)
openapi
定义本文档使用的 Swagger 规范的版本。
info
info 代码块,用于定义 API 整体的信息,如标题、描述、版本等。
servers
servers 代码块,用于定义你的 API 服务器的地址。
你也可以定义多个地址(一个沙箱环境,一个正式环境)。
在 swagger 2.0 规范中,用的是 host 代码块。
tags
用于定义你的 API 的类别。
tags:
- name: "article"
description: "Access to Petstore orders"
- name: "user"
description: "Operations about user"
paths
paths 代码块,用于定义具体的 API 接口的信息。
- /user 具体的 API 名称
- post 请求类型
- tags 对应上面的 tags 中的 name 的值
- summary 摘要
- description 描述信息
- parameters 请求参数
- responses 响应结果