一、 Swagger格式入门

在Ubuntu上，Swagger是一个非常受欢迎的API框架，它为开发者给了有力巨大的API文档自动生成功能。先说说让我们来看看Swagger支持哪些格式。

二、 Swagger支持的格式详解

1. JSON格式

Swagger配置文件能用JSON格式编写。这种格式以键值对的形式组织数据，容易于阅读和编辑。

{
  "swagger": "2.0",
  "info": {
    "title": "Sample API",
    "description": "A sample API to demonstrate Swagger configuration",
    "version": "1.0.0"
  },
  "host": "",
  "basePath": "/v1",
  "schemes": ,
  "paths": {
    "/users": {
      "get": {
        "summary": "List all users",
        "description": "Returns a list of users",
        "responses": {
          "200": {
            "description": "An array of users",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/User"
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "User": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      }
    }
  }
}
    

2. YAML格式

Swagger配置文件也能用YAML格式编写。这种格式以分层的方式组织数据，适用于更麻烦的配置。

swagger: '2.0'
info:
  title: Sample API
  description: A sample API to demonstrate Swagger configuration
  version: '1.0.0'
host: ''
basePath: /v1
schemes:
  - https
paths:
  /users:
    get:
      summary: List all users
      description: Returns a list of users
      responses:
        '200':
          description: An array of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      email:
        type: string

三、 在Ubuntu上用Swagger的步骤

1. 安装Swagger工具

先说说您需要在Ubuntu上安装Swagger命令行工具和Swagger UI。能通过以下命令完成安装：

sudo apt update
sudo apt install nodejs npm
npm install -g swagger-jsdoc swagger-ui-express

2. 创建Swagger配置文件

在您的项目根目录下创建一个名为 swagger.json 或 swagger.yaml 的文件，具体取决于您选择的格式。这玩意儿文件将包含您的API定义。

3. 用npm安装Swagger命令行工具和Swagger UI

接下来 用npm来安装Swagger命令行工具和Swagger UI，这将帮您生成API文档和UI界面。

四、 Swagger UI的用

在应用程序中用Swagger UI，您能通过以下步骤来集成Swagger UI：

1. 在pom.xml文件中添加Swagger相关依赖。
2. 引入swagger支持的jar包。
3. 打开官网， 导入json，地址为： 页面上有一个Live Demo按钮，点击就能打开一个在线的Swagger UI。

Swagger给了灵活的格式支持，包括JSON和YAML，使得API文档的编写和展示更加方便。在Ubuntu上用Swagger，您能轻巧松地创建和测试API文档，搞优良开发效率。

---