OpenAPI 3.0 规范-食用指南

🚀 优质资源分享 🚀

学习路线指引（点击解锁）	知识定位	人群定位
🧡 Python实战微信订餐小程序 🧡	进阶级	本课程是python flask+微信小程序的完美结合，从项目搭建到腾讯云部署上线，打造一个全栈订餐系统。
💛Python量化交易实战💛	入门级	手把手带你打造一个易扩展、更安全、效率更高的量化交易系统

概述

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

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

OpenAPI 的其余功能都是基于这 8 根对象扩展而成，凡是包含以上对象并且扩展名为 json，yaml 的文件，我们可以将其视为符合 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 文件就诞生了，它的展示方式如下：

• 上面灰色的 1.0 是指你 server 的版本
• OAS3 指的是你所使用的 OpenAPI 规范的版本

info 对象

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

• title： 标题
• description: API 描述
• version：版本号
• license：许可证信息
• contact：联系人信息
• terms of service：服务条款

以下是 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: {}

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

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

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

• 描述整个 API 和如何使用它
• 为用户提供测试账号和数据
• 其他任何用户需要的信息都可以通过它来提供