如何利用Swagger在Linux上进行API文档共享 - 问答

在Linux上利用Swagger进行API文档共享，可以按照以下步骤进行：

1. 安装Swagger Editor和Swagger UI

使用Docker容器部署

安装Docker：

sudo apt-get update
sudo apt-get install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

拉取Swagger Editor镜像：

docker pull swaggerapi/swagger-editor:v4.6.0

运行Swagger Editor容器：

docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0

拉取Swagger UI镜像：

docker pull swaggerapi/swagger-ui:v4.15.5

运行Swagger UI容器：

docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5

手动安装

安装Node.js和npm：

sudo apt-get update
sudo apt-get install -y nodejs npm

下载并解压Swagger Editor和Swagger UI：

mkdir -p /opt/swagger
cd /opt/swagger
wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
tar -xvf v3.16.1.tar.gz
rm v3.16.1.tar.gz
cd swagger-editor-3.16.1
npm install
nohup http-server -p 8080 &

下载并解压Swagger UI：

cd ..
git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui
npm install
npm run start

2. 创建和配置OpenAPI规范文件

创建一个OpenAPI规范文件（通常为YAML或JSON格式），用于描述您的API。例如，一个名为swagger.yaml的文件：

swagger: '2.0'
info:
  title: 测试Swagger API文档
  version: 1.0.0
  description: 此文档用于测试Swagger API
  contact:
    name: 行百里er
    url: https://mp.weixin.qq.com/mp/profile_ext?action=home&__biz=MzI1MDU1MjkxOQ==
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
schemes:
  - http
host: traveler100.com
basePath: /api/v1
paths:
  /user/{mobile}:
    get:
      summary: 获取用户信息 (根据手机号)
      description: 根据提供的手机号获取用户信息
      parameters:
        - name: mobile
          in: path
          required: true
          description: 用户手机号
          type: string
      responses:
        '200':
          description: 成功
          schema:
            type: object
            properties:
              username:
                type: string
              password:
                type: string

3. 生成和访问API文档

生成API文档：

swagger generate spec -o ./swagger.json

启动Swagger服务：
```
swagger serve --no-open ./swagger.json
```
访问Swagger UI：
- 使用Docker容器部署时，访问 http://:38080 来使用Swagger Editor，访问 http://:38081 来使用Swagger UI。
- 手动安装时，访问 http://:8080 来使用Swagger Editor，访问 http://:3000/swagger 来使用Swagger UI。

4. 集成Spring Boot项目（可选）

如果您使用Spring Boot项目，可以使用 springdoc 库来集成Swagger。

添加依赖：在 pom.xml 中添加以下依赖：

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.1.0</version>
</dependency>

配置Swagger：创建一个配置类来启用Swagger：

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(info = @Info(title = "Your API Title", version = "1.0", description = "Your API Description"))
public class SwaggerConfig {
    // 这里可以添加更多的配置,如果需要的话
}

启动Spring Boot应用：使用Maven构建并启动你的Spring Boot应用。
访问Swagger UI：启动应用后，访问 http://localhost:8080/swagger-ui 即可查看生成的API文档。

通过以上步骤，您可以在Linux上成功搭建Swagger环境，实现API文档的共享和管理。

0 赞

0 踩