OpenAPI 3.0.0 学习 之 老版本2.0通过Swagger Editor编写接口文档

PS：时间关系，先打一下草稿，日后整理相关细节。

 

OpenAPI 3 / Swagger API 模拟服务器（cmd命令框运行exe文件）：http://stoplight.io/platform/prism/

Swagger在线编辑器（该款在线编辑器可以实现 json 与 yaml 转换，一般推荐使用yaml）：http://editor.swagger.io/

1. 首先准备一份后缀名为yaml的文件，以下为内容：

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - http
host: localhost:4010
basePath: /

paths:
  /user:
    get:
      summary: Gets some persons
      tags:
      - "user"
      
      description: Returns a list containing all persons. The list supports paging.
      produces: #这个一定要写，不然浏览器显示不出来
       - 'application/json'
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - ids
              properties:
                ids:
                  type: string
                username:
                  type: string
                password:
                  type: string
    

PS：example是写给自己看的，数据都是自动随机生成。自我感觉这样测试数据非常好

2. 执行模拟器，swagger.yaml可以是json文件

   相关细节可以参考官方文档：https://help.stoplight.io/prism/getting-started/prism-introduction（看不懂的可以直接谷歌浏览器打开，直接页面翻译，比较好用准确）

   

PS：起初没有加cors，浏览器可以直接访问，但是在Swagger Editor不能查看生成的数据，加上cors就可以访问，关于cors的资料日后再补充。

3.查看生成的数据

PS：附上几个学习OpenAPI好用的网站。

         OpenAPI3.0.0：https://www.breakyizhan.com/swagger/2991.html

        如何编写基于OpenAPI规范的API文档