Linux下Swagger的API文档如何生成

在Linux环境下，生成Swagger API文档通常涉及以下步骤：

1. 安装Swagger工具： 你可以使用Swagger Codegen或OpenAPI Generator来生成API文档。这里以Swagger Codegen为例。

   # 安装Swagger Codegen
   wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.23/swagger-codegen-cli-2.4.23.jar
   

2. 准备Swagger规范文件： 你需要一个Swagger规范文件（通常是YAML或JSON格式），描述你的API。这个文件可以从你的代码中自动生成，或者手动编写。

   swagger: '2.0'
   info:
     title: Sample API
     description: This is a sample server Petstore server.
     version: 1.0.0
   paths:
     /pets:
       get:
         summary: List all pets
         responses:
           '200':
             description: An array of pets
             schema:
               type: array
               items:
                 $ref: '#/definitions/Pet'
   definitions:
     Pet:
       type: object
       properties:
         id:
           type: integer
           format: int64
         name:
           type: string
         tag:
           type: string
   

3. 生成API文档： 使用Swagger Codegen CLI工具生成API文档。你可以选择生成不同类型的文档，比如HTML、Markdown、Java客户端代码等。

   # 生成HTML文档
   java -jar swagger-codegen-cli-2.4.23.jar generate \
     -i http://petstore.swagger.io/v2/swagger.json \
     -l html2 \
     -o ./docs
   

   这个命令会从http://petstore.swagger.io/v2/swagger.json下载一个示例Swagger规范，并生成HTML格式的API文档到./docs目录。

4. 查看生成的文档： 生成的HTML文档可以在浏览器中打开查看。

   # 打开生成的HTML文档
   firefox ./docs/index.html
   

如果你更喜欢使用OpenAPI Generator，步骤类似：

1. 安装OpenAPI Generator：

   # 安装OpenAPI Generator
   brew install openapi-generator
   

2. 准备Swagger规范文件： 同样需要一个Swagger规范文件。

3. 生成API文档：

   # 生成HTML文档
   openapi-generator-cli generate \
     -i http://petstore.swagger.io/v2/swagger.json \
     -g html2 \
     -o ./docs
   

4. 查看生成的文档：

   # 打开生成的HTML文档
   firefox ./docs/index.html
   

通过这些步骤，你可以在Linux环境下生成并查看Swagger API文档。