Swagger编写API文档的YAML

最新推荐文章于 2025-06-29 09:29:58 发布

原创

最新推荐文章于 2025-06-29 09:29:58 发布 · 7.8k 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#Swagger #YAML #编写yaml格式文件

本文档详细介绍了如何使用Swagger规范2.0编写YAML格式的API接口文档。包括了Swagger元数据定义，如标题、描述和版本，以及GET、POST、DELETE、PATCH等HTTP操作方法的详细描述，包括响应状态码、请求参数、响应数据模型等。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

    # 
   必要字段！ 
   Swagger规范版本， 
   必须填2. 
   0， 
   否则该YAML将不能用于Swagger其他组件 
  
   swagger: 
   '2.0' 
  
    # 
   必要字段！ 
   描述API接口信息的元数据 
  
   info: 
  
    # 
   接口标题 
  
   title: 
   swagger说明文档　 
  
    # 
   接口文档的描述 
  
   description: 
   学习Swagger 
  
    # 
   版本号 
  
   version: 
   1.0. 
   0 
  
    # 
   Swagger会提供测试用例， 
   host指定测试时的主机名， 
   如果没有指定就是当前主机, 
   可以指定端口． 
  
   host: 
   127.0. 
   0.1 
  
    # 
   定义的api的前缀， 
   必须已/ 
   开头, 
   测试用例的主机则为: 
   host＋ 
   bashPath 
  
   basePath: / 
   api 
  
    # 
   指定调用接口的协议， 
   必须是: 
   "http", 
   "https", 
   "ws", 
   "wss"． 
   默认是http.- 
   表示是个数组元素， 
   即schemes接受一个数组参数 
  
   schemes: 
  
    - 
   http 
  
    - 
   https 
  
    # 
   对应与http协议头request的Accept， 
   调用者可接受类型, 
   默认是* 
   /*,定义的类型必须是http协议定义的 Mime Types,RestfulAPI一般定义成application/json 
  
   #这两个是对所有接口的全局设置，在细化的接口中是还可以对应这两个属性来覆盖全局属性 
  
   produces: 
  
    - application/json 
  
   #必要字段!定义可有可操作的API 
  
   paths: 
  
    /users: 
  
    #必要字段!定义HTTP操作方法，必须是http协议定义的方法 
  
    get: