任何项目在开发完成后都需要编写接口文档,而手动编写文档即消耗人力又可能由于维护不及时导致文档和项目版本不一致,反之如果使用swagger在项目更新的同时自动生成相应的接口文档则可以避免上述问题。由于swagger2.0的规范依赖于openapi 3.0版本的规范，所以在使用swagger生成文档前，了解和掌握openapi的规范是必要的,所以我下边列出了openapi文档的常用示例并赋予中文说明:

官方文档（中文版）

The OpenAPI Specification | 开放API规范

openapi: "3.0.0"
info:  //提供API相关的元数据
  version: 1.0.0   //必选. API文档的版本信息(注意:这个版本和开放API 规范版本没有任何关系)。
  title: Swagger Petstore  //必选. 应用的名称。
  description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification //对应用的简短描述。 CommonMark syntax 可以被用来 表示富文本呈现。
  termsOfService: http://swagger.io/terms/   //指向服务条款的URL地址，必须是URL地址格式。
  contact:                                  //所开放的API的联系人信息。
    name: Swagger API Team
    email: apiteam@swagger.io
    url: http://swagger.io
  license:                                  //所开放的API的证书信息。
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:   //这是一个Server对象的数组， 提供到服务器的连接 信息。如果没有提供 servers 属性或者是一个空数 组，那么默认为是url值为 / 
  - url: http://petstore.swagger.io/api   //必选. 指向目标主机的URL地址。
    description: The production API server  //一个可选的字符串，用来描述此URL地址
    variables:    //一组变量和值的映射，这些值被用来替换服务器URL地 址内的模板参数。
        username:
            default: demo     //必选. 当可替换的值没有被使用者指定时使用的默认值。
            description: this value is assigned by the service provider    //对服务器变量的可选的描述
        port: 
            enum:               //一组可枚举字符串值，当可替换选项只能设置为固定的某些 值时使用。
               - 8443
               - 443
            default: 8443
        basePath: 
            default: v2
paths: //必选。对所提供的API有效的路径和操作。
  /pets:   //到各个端点的相对路径，路径必须以 / 打头，这个路径会被直接连接 到 Server 对象 的 url 字段以组成完整URL地址 当做URL地址匹配时，不 带路径参数的路径会被优先匹配。应该避免定义多个具有相同路径层 级但是路径参数名不同的路径，因为他们是等价的。当匹配出现歧义 时，由使用的工具自行决定使用那个路径。
    $ref: ''  //指定对此路径的外部定义的引用
    description: ''//可选描述字段
    summary: ''  //可选 描述包含的操作
    get:
      description: |
        Returns all pets from the system that the user 
      operationId: findPets   //用于标识此操作的 唯一字符串，这个 id在此API内包含 的所有操作中必须 是唯一的。
      tags:     //用于控制API文档 的标签列表，标签 可以用于在逻辑上 分组对资源的操作 或作为其它用途的 先决条件。
        - test
      parameters:
        - name: tags  //必选. 参数的名称。参数名是区分大小写。
          in: query   //必选. 参数的位置，可能的值有 "query", "header", "path" 或 "cookie"。
          description: tags to filter by
          required: false
          style: form
          schema:
            type: array
            items:
              type: string
        - name: limit
          in: query
          description: maximum number of results to return
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      servers:   //一个可用于此操作 的额外的 server 数组，这里的定义 会覆盖 Path Item 对象 或 顶层的定 义。
        - url: 
      callbacks:  //回调 内容和path item一致
        {path}
    post:
      description: Creates a new pet in the store. Duplicates are allowed
      operationId: addPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'
      responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pets/{id}:
    get:
      description: Returns a user based on a single ID, if the user does not have access to the pet
      operationId: find pet by id
      parameters:
        - name: id
          in: path
          description: ID of pet to fetch
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      description: deletes a single pet based on the ID supplied
      operationId: deletePet
      parameters:
        - name: id
          in: path
          description: ID of pet to delete
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: pet deleted
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:  //包含开放API规范固定的各种可重用组件。 这里只提供schema示例，其余的（如header,response等）请自行查看openapi 3.0文档
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/PetV1'
        - $ref: '#/components/schemas/PetV2'
      discriminator: //如何区分不同的模式，来如何进行序列化和反序列化
          propertyName: version //包含区分符值的属性的名称。
          mapping:
            1.0: '#/components/schemas/PetV1'
            2.0: '#/components/schemas/PetV2'
    PetV2:
      allOf:
        - $ref: '#/components/schemas/PetV1'
        - type: object
          required:
          properties:
              type: integer
              format: int64
    PetV1:
      type: object
      required:
        - name  
      properties:
        name:
          type: string
        tag:
          type: string 
        address:
          $ref: '#/components/schemas/Address'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          minimum: 100
          maximum: 600
        message:
          type: string
                    前言任何项目在开发完成后都需要编写接口文档,而手动编写文档即消耗人力又可能由于维护不及时导致文档和项目版本不一致,反之如果使用swagger在项目更新的同时自动生成相应的接口文档则可以避免上述问题。由于swagger2.0的规范依赖于openapi 3.0版本的规范，所以在使用swagger生成文档前，了解和掌握openapi的规范是必要的,所以我下边列出了openapi文档的常用示例并赋予中文...
				
OpenAPI 3查看器
此服务旨在轻松浏览和测试（fka Swagger规范）中描述的REST API。 该服务主要使用组件。 它还提供了一个简单的用于代理目的的nodeJS后端。
 实际操作：
克隆该项目，然后使用npm install或yarn安装依赖项：
 npm run dev
使用Docker启动服务
Docker映像在上公开可用。
 运行以下命令：
 docker run -p 8080:8080 koumoul/openapi-viewer
您可以使用以下查询参数来预填充查看器
url ：要加载的API文档文件的位置，采用OpenAPI v3 JSON格式。
 proxy ：如果要使用此服务后端作为代理来获取API文档文件，则为true或false。 默认为false。 如果无法通过CORS标头访问API描述，则可能很有用。 如果要访问位于loc
OpenAPI 规范（OAS）定义了一个标准的、语言无关的 RESTful API 接口规范，它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码，文档或网络流量检查（既方便人类学习和阅读，也方便机器阅读）。正确定义 OAS 后，开发者可以使用最少的实现逻辑来理解远程服务并与之交互。
此外，文档生成工具可以使用 OpenAPI 规范来生成 API 文档，代码生成工具可以生成各种编程语言下的服务端和客户端代码，测试代码和其他用例。
OAS 使用
OpenAPI规范(以前叫swagger规范)是一个接口文档规范，它用一个文件来描述API接口，包括：
可用的api接口(如/users) 和接口方法 (GET /users, POST /users)
输入和输出参数
联系信息, 代码许可, 使用条款和其他信息等.
文件可是可以是json或yaml的，完整的规范参见: OpenAPI 3.0 Specification
什么是swagger
Swagger is a set of open-
				
OpenAPI 是什么?
Open API 即开放 API，也称开放平台。 所谓的开放 API（OpenAPI）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列
API（Application Programming Interface，应用编程接口）开放出去，供第三方开发者使用，这种行为就叫做开放网站的 API，所开放的 API 就被称作 OpenAPI（开放 API ）。...
				
文章目录前言一、swagger 3 的使用SwaggerSpringFox3.0 相关特性SpringDoc二、从 spring-fox 迁移到 springdoc三、使用 swagger3 注解代替 swagger2 的（可选）
Swagger2（基于openApi3）已经在17年停止维护了，取而代之的是 sagger3（基于openApi3），而国内几乎没有 sagger3使用的文档，百度搜出来的都是swagger2的使用，这篇文章将介绍如何在 java 中使用 openApi3（swagge
				
看到时间流逝真是太恐怖了！ OpenAPI规范3.0.0是对Swagger规范的重大修改，大部分已于一年前发布，但是工具赶上了一段时间。 但是，随着Swagger Core 2.0.0的最新正式发布，事情肯定会加速。 
 为了证明这一点，著名的JAX-RS 2.1实现Apache CXF是OpenAPI 3.0.0的最早采用者之一，在今天的帖子中，我们将了解一下JAX-RS 2.1 API可...
				
OpenAPI 3.0规范是一个由多个根对象组成的规范，其中包括openapi、info、servers、paths、components、security、tags和externalDocs。在OpenAPI 3.0规范中，我们首先需要指定使用的规范版本，通过在openapi属性中设置值为"3.0.2"来指定使用OpenAPI 3.0.2版本的规范。
接下来，我们可以继续补充信息。在info对象中，我们可以设置title属性来指定OpenAPI文档的标题，同时可以设置version属性来指定文档的版本。在paths对象中，我们可以定义API的路径和操作。在components对象中，我们可以定义可重复使用的组件，如schemas、parameters和responses等。在security对象中，我们可以定义API的安全机制。在tags对象中，我们可以对API进行标记分类。最后，在externalDocs对象中，我们可以提供外部文档的链接。通过使用这些根对象，我们可以按照规范构建和描述我们的API。<span class="em">1</span><span class="em">2</span><span class="em">3</span>
#### 引用[.reference_title]
-  *1* *2* *3* [OpenAPI 3.0 规范-食用指南](https://blog.csdn.net/m0_56069948/article/details/125468864)[target="_blank" data-report-click={"spm":"1018.2226.3001.9630","extra":{"utm_source":"vip_chatgpt_common_search_pc_result","utm_medium":"distribute.pc_search_result.none-task-cask-2~all~insert_cask~default-1-null.142^v93^chatsearchT3_1"}}] [.reference_item style="max-width: 100%"]
[ .reference_list ]