ubuntu

Ubuntu上Swagger文档怎么生成

小樊
41
2025-05-05 13:47:59
栏目: 智能运维

在Ubuntu上生成Swagger文档,通常涉及以下几个步骤:

安装Swagger工具

首先,你需要安装Swagger UI和Swagger Editor。可以通过npm(Node.js的包管理器)来安装:

# 安装Node.js和npm(如果尚未安装)
sudo apt update
sudo apt install -y nodejs npm

# 全局安装Swagger UI和Swagger Editor
npm install -g swagger-ui-express swagger-editor-cli

编写API规范

使用OpenAPI Specification(OAS)编写API规范文件,通常是swagger.yamlswagger.json格式。例如,一个简单的swagger.yaml文件示例:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: An array of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

生成API文档

使用Swagger Codegen CLI工具生成API文档。以下命令将生成HTML格式的API文档:

java -jar swagger-codegen-cli.jar generate \
  -i path/to/swagger.yaml \
  -l html2 \
  -o path/to/output/directory

path/to/swagger.yaml替换为你的OpenAPI规范文件的实际路径,将path/to/output/directory替换为你希望输出文档的目录。

集成到构建过程(可选)

你可以将Swagger Codegen集成到Maven或Gradle的构建过程中,以便在每次构建时自动生成代码和文档。以下是Maven和Gradle的集成示例:

Maven插件示例:

<build>
  <plugins>
    <plugin>
      <groupId>org.openapitools</groupId>
      <artifactId>openapi-generator-maven-plugin</artifactId>
      <version>5.2.1</version>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${project.basedir}/src/main/resources/swagger.yaml</inputSpec>
            <generatorName>java</generatorName>
            <output>${project.build.directory}/generated-sources</output>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Gradle任务示例:

plugins {
  id 'org.openapitools.codegen' version '5.2.1'
}

openApiGenerate {
  inputSpec = file("projectDir/src/main/resources/swagger.yaml").toString()
  generatorName = 'java'
  outputDir = file("buildDir/generated-sources")
}

通过以上步骤,你可以在Ubuntu上成功生成Swagger文档。根据具体需求,你可以选择生成不同语言的客户端代码,或者生成不同格式的API文档。

0
看了该问题的人还看了