swagger的yaml规则-初始化

本文档介绍了Swagger YAML的初始设置和基本规则,旨在帮助开发者更好地理解和使用Swagger来描述RESTful API。通过学习,您可以掌握如何用YAML定义API接口、模型及参数等关键概念。
摘要由CSDN通过智能技术生成
swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
  description: "Everything about your Pets"
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
- name: "store"
  description: "Access to Petstore orders"
- name: "user"
  description: "Operations about user"
  externalDocs:
    description: "Find out more about our store"
    url: "http://swagger.io"
schemes:
- "http"
paths:
  /pet:
    post:
      tags:
      - "pet"
      summary: "Add a new pet to the store"
      description: ""
      operationId: "addPet"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Pet"
      responses:
        405:
          description: "Invalid input"
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"
    put:
      tags:
      - "pet"
      summary: "Update an existing pet"
      description: ""
      operationId: "updatePet"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Pet"
      responses:
        400:
          description: "Invalid ID supplied"
        404:
          description: "Pet not found"
        405:
          description: "Validation exception"
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"
  /pet/findByStatus:
    get:
      tags:
      - "pet"
      summary: "Finds Pets by status"
      description: "Multiple status values can be provided with comma separated strings"
      operationId: "findPetsByStatus"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - name: "status"
        in: "query"
        description: "Status values that need to be considered for filter"
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "available"
          - "pending"
          - "sold"
          default: "available"
        collectionFormat: "multi"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Pet"
        400:
          description: "Invalid status value"
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"
  /pet/findByTags:
    get:
      tags:
      - "pet"
      summary: "Finds Pets by tags"
      description: "Muliple tags can be provided with comma separate
Swagger 是一种用于设计、构建和文档化 API 的工具集,它提供了一套标准的协议,使得开发者能够方便地查看和测试 API 接口。当提到“点击接口打开新窗口”时,通常指的是如何通过 Swagger UI 来展示 API 接口,并允许用户在点击某个接口时在新的浏览器标签页或窗口中预览该接口的具体信息和参数。 以下是实现这一功能的基本步骤: ### 步骤 1: 创建 Swagger 文档 首先,你需要创建或配置一个 Swagger 文档,这通常涉及到描述你的 API 端点、请求方法、参数、响应内容等信息。你可以选择手动编写 YAMLJSON 格式的文件,或者是使用一些框架(如 Spring Boot、Django 等)自带的 Swagger 支持来自动生成文档。 ### 步骤 2: 集成 Swagger UI 将生成的 Swagger 文档集成到你的项目中,可以使用 Swagger UI 自动加载并渲染文档页面。一般的做法是在项目的 HTML 页面中引入 Swagger UI 的静态资源(CSS 和 JavaScript 文件),然后指向你的 Swagger YAMLJSON 文件的 URL。例如,在 `<head>` 区域添加: ```html <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@next/swagger-ui.css"> <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@next/swagger-ui-bundle.js"></script> ``` 接着,在 `<body>` 中添加一个容器元素,并指定其 `id` 以便于后续的脚本操作: ```html <div id="swagger-ui"></div> ``` ### 步骤 3: 初始化 Swagger UI 通过 JavaScript 加载 Swagger UI 并初始化它,通常需要传递 Swagger 文档的 URL 到特定函数中: ```javascript window.onload = function () { const ui = SwaggerUIBundle({ url: 'path/to/your/swagger-document', // 替换为实际的 Swagger 文档路径 dom_id: '#swagger-ui', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: "BaseLayout", showExtensions: true, showRequestResponseData: true }); }; ``` 在这个脚本中,`deepLinking` 参数允许直接通过 URL 访问某个端点的详细信息页面,用户可以在 Swagger UI 的左侧导航栏中选择接口,并通过点击来访问接口的详细信息页面。 ### 步骤 4: 用户交互与新窗口打开 为了实现点击接口打开新窗口的功能,你可以在 Swagger UI 的右侧部分添加自定义的按钮或链接,引导用户跳转到接口的详细信息页面并在新窗口中显示。这通常涉及 JavaScript 编程来监听事件并触发新窗口的打开动作。例如: ```javascript // 假设有一个按钮或链接被添加到了 Swagger UI 的布局中 ui.listen("click", ".tag-filter a", (event) => { window.open(event.target.href.split('#'), '_blank'); }); ``` 以上就是使用 Swagger 实现点击接口打开新窗口的基本流程。通过这样的设置,不仅提升了 API 的可用性和易用性,也便于团队成员之间的沟通和协作。当然,具体的实现细节会依据所使用的技术栈和框架有所不同。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值