其他分享
首页 > 其他分享> > OpenAPI 3.0 规范-食用指南

OpenAPI 3.0 规范-食用指南

作者:互联网

概述

OpenAPI 3.0 规范由 8 个根对象组成:

  1. openapi
  2. info
  3. servers
  4. paths
  5. components
  6. security
  7. tags
  8. externalDocs

OpenAPI 的其余功能都是基于这 8 根对象扩展而成,凡是包含以上对象并且扩展名为 jsonyaml 的文件,我们可以将其视为符合 OpenAPI 规范的描述文件 ,你可以在:API Editor 在线编辑器 中来验证你的 OpenAPI 文件是否符合规范,以下我们就主要介绍 8 个根对象的使用和扩展方法

openapi 对象

openapi 是最简单也是最基础的属性,我们为 OpenAPI 添加第一个根对象属性,指定使用的规范版本:

openapi: "3.0.2"

然后继续补充信息

openapi: "3.0.2"
info:
  title: openAPI Demo
  version: '1.0'
paths: {}

一个极简的 OpenAPI 文件就诞生了,它的展示方式如下:

image-20220617125753764

info 对象

根节点的 info 对象主要包含以下信息:

以下是 info 对象和属性的示例:

openapi: "3.0.2"
info:
  title: openAPI Demo
  description: "This is an API program for teaching"
  version: '1.1'
  termsOfService: "https://openweathermap.org/terms"
  contact:
    name: "api developer"
    url: "http://myblog.cn"
    email: "youemai@gmail.com"
  license:
    name: "Apache 2.0"
    url: "http://springdoc.org"
paths: {}

以上内容的预览效果如下:

image-20220617132722173

如果觉得 description 太过简陋,它也支持 Markdown 语法显示,效果如下:

image-20220617133225602

按照约定 description 应该向用户展示如下信息:

servers 对象

servers 主要表示访问服务端的基础路径,既在访问接口前都会带上该参数,示例如下:

servers:
  - url: 'http://localhost:8080/webapi'
image-20220618234009839

servers 对象支持多参数配置,你可以指定多服务器(开发,测试,生成等)的 URL,用户可以从下拉框选择不用服务器的 URL 发起请求,配置和预览效果如下:

servers:
- url: https://localhost:8080/webapi
  description: develop server
- url: http://test-server:8080/webapi
  description: test server
- url: http://product-server:8080/webapi
  description: product server
image-20220618233542570

paths 对象

paths 对象包含真正的 API 信息内容,它的每个项都包含一个可操作的 endpoint 操作对象,每个操作对象都包含我们常见的 GET/POST/PUT/DELETE 等方法,看一个简单示例:

paths:
  /pet:
    get:

以上信息描述一个 /petendpoint ,它只包含一个 get 操作对象,类似 get 操作对象(也称 Operation Objects)也包含以下属性:

大多数情况下不需要声明那么多的属性,以下是一个端点的 operation object 常见描述信息,如下:

paths:
  /weather:
    get:
      tags:
      summary:
      description:
      operationId:
      externalDocs:
      parameters:
      responses:

parameters 对象

parameters 的示例用法(包含一个参数的 get 方法):

paths:
  /weather:
    get:
      tags:
      - Current Weather Data
      summary: "Call current weather data for one location."
      description: "^_^"
      operationId: CurrentWeatherData
      parameters:
      - name: q
        in: query
        description: "^_^"
        schema:
          type: string

responses 对象

responses 用于描述接口的响应对象,可以直接描述,如下:

responses:
  200:
    description: Successful response
    content:
      application/json:
        schema:
          title: Sample
          type: object
          properties:
            placeholder:
              type: string
              description: Placeholder description

  404:
    description: Not found response
    content:
      text/plain:
        schema:
          title: Weather not found
          type: string
          example: Not found

你可以在 Swagger UI 中看到以下的示例效果:

image-20220623211039935

components 对象

components 中主要可以定义重复使用的对象,以便其他对象使用 $ref 关键字直接引用和声明

在 parameters 中重用对象

我们可以把刚才对 parameters 的描述移动到 components 中来,如下:

components:
  parameters:
    q:
      name: q
      in: query
      description: "………………"
      schema:
        type: string
    id:
      name: id
      in: query
      description: "…………"
      schema:
        type: string
    lat:
      name: lat
      in: query
      description: "………………"
      schema:
        type: string

然后我们可以在 paramters 中直接引用它,如下:

paths:
  /weather:
    get:
      tags:
      - Current Weather Data
      summary: "………………"
      description: "………………."
      operationId: CurrentWeatherData
      parameters:
        - $ref: '#/components/parameters/q'
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/lat'
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                title: Sample
                type: object
                properties:
                  placeholder:
                    type: string
                    description: Placeholder description
        404:
          description: Not found response
          content:
            text/plain:
              schema:
                title: Weather not found
                type: string
                example: Not found

如上,利用好 components 就可以达到组件复用 +减少篇幅的效果

在 reponses 中重用对象

我们也可以直接在 reponses 中引用已经声明的对象,如下:

responses:
  200:
    description: Successful response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/200'

它在 yaml 中的描述如下:

components:
  schemas:
    200:
      title: Successful response
      type: object
      properties:
        base:
          type: string
          description: Internal parameter
          example: cmc stations
        visibility:
          type: integer
          description: Visibility, meter
          example: 16093
        dt:
          type: integer
          description: Time of data calculation, unix, UTC
          format: int32
          example: 1435658272
        id:
          type: integer
          description: City ID
          format: int32
          example: 2172797
        name:
          type: string
          example: Cairns
        cod:
          type: integer
          description: Internal parameter
          format: int32
          example: 200

它在 Swagger UI 中展示效果如下:

image-20220623221100016

在 schemas 中展示

通过 components 定义的对象都会在 Swagger UI 下方通过 Schemas 进行展示,如下:

image-20220623221314193

security 对象

除了部分 Demo 示例外,大部分的 Web 服务都是需要经过身份认证的才能访问,security 就是用于描述 API 的安全信息和访问授权协议等信息的对象,OpenAPI 支持最常见的四种授权方案,如下:

这里我们使用最常见的 API Key 作为演示,在 OpenAPI 文档的根目录添加安全对象:

security:
  - app_id: []

这样所有的路径都会使用 security 描述的 app_id 安全方法,但是通常会在 components 中添加 security 对象,这样的描述信息会更加的详细,如下:

components:
  ...
  securitySchemes:
    app_id:
      type: apiKey
      description: API key to authorize requests.
      name: appid
      in: query

security 对象的属性内容:

在添加以上的描述信息后,Swagger UI 会显示安全任何的相关标识,如下:

image-20220626001754782

点击 Authorize 会显示更多的安全信息:

image-20220626001929858

当你在 Value 输入你的访问秘钥时,Swagger 会在访问 API 的时候,根据你的设定访问你的 API,如下:

image-20220626002200263

tags 对象

该对象主要是对 OpenAPI 中的多个访问路径进行分组,从而更方面的查看 API 信息,使用示例如下:

我们为一个请求路径添加 tags 信息:

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets

这表示该请求路径属于 pets 分组,然后我们在根目录级别添加 tags 属性,来为分组信息进行描述:

tags:
  - name: pets
    description: "Chimelong Animal Happy World"

然后我们来看看 Swagger UI 对于分组信息的展示,如下:

image-20220626003256305

externalDocs 对象

该对象不常用,主要添加对外部文档的引用,来对目前文档进行补充,例如你可以在根目录添加该属性,如下:

externalDocs:
  description: externalDocs API Documentation
  url: https://openweathermap.org/api

它会在你 Swagger 的描述中展示一个链接地址,如下:

你还可以在 API 的请求路径中,增加一个外部引用的描述,如下:

paths:
  /pets:
    get:
      summary: List all pets
      externalDocs:
        description: externalDocs API Documentation
        url: https://openweathermap.org/api

Swagger UI 会在请求路径的描述中,增加一个外部链接作为对描述的补充,如下:

image-20220626004102765

总结

以上就是一个完整的 OpenAPI 规范的文件的使用说明

参考资料:

标签:指南,description,对象,components,OpenAPI,API,3.0,type
来源: https://www.cnblogs.com/xiao2shiqi/p/16412813.html