Swagger导出文档详解

发布时间：2023-05-19

Swagger是一种RESTful API文档化和交互的工具，在API开发中使用较为广泛。同时，Swagger也提供了导出API文档的功能，以便于开发人员和用户查看API接口的相关信息。本文将从多个方面详细阐述Swagger导出文档的相关内容。

一、导出文档格式

Swagger支持导出文档的格式有：YAML、JSON、Markup和AsciiDoc。其中，YAML和JSON格式比较常见，Markup和AsciiDoc格式在实际开发中使用较少。 以YAML格式导出文档为例：

swagger: '2.0'
info:
  version: 1.0.0
  title: Sample API
  description: A sample API
basePath: /v1
produces:
  - application/json
paths:
  /users:
    get:
      summary: Retrieves a list of users
      description: Retrieves a list of users
      responses:
        200:
          description: A list of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      email:
        type: string

其中，swagger: '2.0'表示Swagger的版本；info中包含了API的基本信息；basePath指定了API的基础路径；produces指定了API的响应格式；paths中包含了API的具体路径和操作；definitions中定义了API的数据模型。

二、导出文档中的API信息

Swagger导出的API文档中，通常包含以下信息：

1. API基本信息

API的基本信息包括：API的名称、版本、描述、协议、主机名和API的基础路径等。

2. API路径和操作

API的路径和操作指的是API接口的具体路径和对该路径的操作，如GET、POST、PUT、DELETE等。针对每个操作，Swagger导出文档通常包含以下信息：

  • summary：操作的简要描述
  • description：操作的详细描述
  • parameters：操作的参数列表，包含参数名、参数类型、参数位置、是否必选、默认值等信息
  • responses：操作执行后的响应列表，包含响应码、响应描述、响应内容等信息

3. API数据模型

Swagger导出文档中也包含了API的请求和响应数据模型的定义，方便开发人员对API数据进行理解和使用。

三、自定义文档主题

Swagger导出文档默认采用的是Swagger UI主题，但是，在实际开发中，我们有时需要对导出文档的主题进行定制。Swagger支持通过配置Swagger UI参数，自定义文档主题。以下是一个示例：

window.onload = function() {
  // Begin Swagger UI call region
  const ui = SwaggerUIBundle({
    url: "http://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout",
    docExpansion: "none",
    operationsSorter: "alpha",
    configUrl: "/swagger-config.json",
    oauth2RedirectUrl: "http://localhost:8000/swagger/oauth2-redirect.html",
    discoveryUrls:[
      "http://localhost:8000/apis/discovery"
    ],
    validatorUrl: "//online.swagger.io/validator"
  })
  // End Swagger UI call region
  window.ui = ui
}

其中，通过配置layout、docExpansion等参数可以改变文档的主题风格。如：StandaloneLayout表示采用单独的布局方式，docExpansion指定API列表是否默认展开等。

四、自定义导出文档

除了自定义文档主题之外，Swagger还支持自定义导出文档。我们可以通过重写Swagger自带的DefaultSwagger2MarkupConfig类，来实现自定义导出文档。以下是一个示例：

public class CustomSwagger2MarkupConfig extends DefaultSwagger2MarkupConfig {
    public CustomSwagger2MarkupConfig() {
        this.setPathsGroupedBy(GroupBy.TAGS);
        this.setInterDocumentCrossReferencesEnabled(false);
        this.setSeparatedDefinitionsEnabled(true);
        this.setGeneratedExamplesEnabled(true);
        this.setListDelimiter('|');
        this.setBasePathPrefix("/api");
    }
}

其中，重写了DefaultSwagger2MarkupConfig类的一些方法，实现了自定义文档的一些特性。

五、结语

Swagger导出文档是API开发中必不可少的一部分，通过本文的介绍，应该可以更好地了解Swagger导出文档相关的细节和技巧。希望本文对大家有所帮助。

推荐文章