Swagger在Linux环境下如何配置与使用

在Linux环境下配置和使用Swagger主要分为以下几个步骤：

1. 安装Node.js和npm

首先，确保你的Linux系统上已经安装了Node.js和npm。如果没有安装，可以参考Node.js官方文档进行安装。

2. 安装Swagger Editor和Swagger UI

安装Swagger Editor

1. 创建一个目录来存放Swagger Editor：

   mkdir /opt/swagger
   cd /opt/swagger
   

2. 下载并解压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
   rm v3.16.1.tar.gz
   

3. 初始化Node.js项目并安装Express：

   npm init -y
   npm install express --save
   

4. 在项目目录中创建一个index.js文件，并添加以下内容来启动HTTP服务器：

   const express = require('express');
   const app = express();
   const port = 8081;
   
   app.use('/swagger-editor', express.static('swagger-editor-3.16.1'));
   
   app.listen(port, () => {
     console.log(`Swagger Editor is running at http://localhost:${port}`);
   });
   

5. 启动服务器：

   node index.js
   

现在，你可以通过访问http://localhost:8081来使用Swagger Editor。

安装Swagger UI

1. 在Swagger Editor的目录中，下载并解压Swagger UI的最新版本：

   wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.48.0.tar.gz
   tar -xvf v3.48.0.tar.gz
   rm v3.48.0.tar.gz
   

2. 初始化Node.js项目并安装Express：

   npm init -y
   npm install express --save
   

3. 在项目目录中创建一个index.js文件，并添加以下内容来启动HTTP服务器：

   const express = require('express');
   const swaggerui = require('swagger-ui-express');
   const swaggerjsdoc = require('swagger-jsdoc');
   
   const swaggerdefinition = {
     openapi: '3.0.0',
     info: {
       title: 'My API Documentation',
       version: '1.0.0',
       description: 'This is my API documentation',
     },
     servers: [{ url: 'http://localhost:3000', description: 'Development server' }],
   };
   
   const options = {
     swaggerDefinition,
     apis: ['./routes/*.js'], // 指向API文档的路径
   };
   
   const swaggerspec = swaggerjsdoc(options);
   
   app.use('/api-docs', swaggerui.serve, swaggerui.setup(swaggerspec));
   
   app.listen(3000, () => {
     console.log('Swagger UI is running at http://localhost:3000/api-docs');
   });
   

4. 启动服务器：

   node index.js
   

现在，你可以通过访问http://localhost:3000/api-docs来使用Swagger UI。

3. 配置Swagger

在你的Spring Boot项目中配置Swagger，可以参考以下步骤：

添加依赖

在你的pom.xml文件中添加以下依赖：

  io.springfox
  springfox-swagger2
  2.7.0


  io.springfox
  springfox-swagger-ui
  2.7.0

配置Swagger

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

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
      .paths(PathSelectors.any())
      .build();
  }
}

使用Swagger注解

在你的Controller中使用Swagger注解来描述API：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Api(tags = "Sample API")
public class SampleController {

  @GetMapping("/hello")
  @ApiOperation(value = "https://www.yisu.com/ask/Say hello", notes = "This is a sample API to demonstrate Swagger usage")
  public String sayHello() {
    return "Hello, World!";
  }
}

4. 访问Swagger文档

启动你的Spring Boot应用程序后，你可以通过访问http://localhost:8080/swagger-ui.html来查看和使用Swagger文档。

通过以上步骤，你就可以在Linux环境下成功配置和使用Swagger了。