ubuntu swagger如何编写文档

在Ubuntu上编写Swagger文档通常涉及以下步骤：

1. 安装Node.js和npm

首先，确保你的系统上已经安装了Node.js和npm。可以通过以下命令来安装：

sudo apt update
sudo apt install nodejs npm

检查安装是否成功：

node -v
npm -v

2. 安装Swagger UI

你可以通过npm全局安装Swagger UI：

sudo npm install -g swagger-ui-express

3. 创建Swagger文档

在你的项目目录中创建一个名为swagger.yaml的文件，这个文件将包含你的API的Swagger规范。以下是一个简单的例子：

swagger: '2.0'
info:
  title: Sample API
  description: A sample API to demonstrate Swagger UI on Ubuntu
  version: '1.0.0'
host: localhost:3000
basePath: /api
schemes:
  - http
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: An array of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
        format: email
        description: The user's name
      email:
        type: string
        format: email
        description: The user's email address

4. 启动Swagger UI

在项目目录中，使用以下命令启动你的应用：

node app.js

应用启动后，你可以在浏览器中访问http://localhost:3000/api-docs来查看Swagger UI界面，并与你的API进行交互。

5. 编写Swagger注释

在你的路由文件或控制器文件中添加JSDoc注释，以定义API文档。例如：

/**
 * @swagger
 * /users:
 *   get:
 *     tags: [users]
 *     summary: 获取用户列表
 *     description: "返回当前所有用户的列表"
 *     responses:
 *       '200':
 *         description: 请求成功
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/user'
 */

6. 使用Swagger Editor

你可以下载Swagger Editor并安装它：

wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
tar -xvf v3.16.1.tar.gz
cd swagger-editor-3.16.1
npm install -g http-server
http-server

然后在浏览器中访问http://localhost:8080来查看和编辑Swagger文档。

通过以上步骤，你就可以在Ubuntu上成功编写和查看Swagger文档了。希望这份指南对你有所帮助！