不同环境下安装Swagger

1. 在基于Maven的Java项目中（Spring Boot项目为例）

  • 步骤一：添加依赖

    • 在项目的pom.xml文件中添加Swagger - UI相关依赖。对于Spring Boot项目，通常会添加springfox-boot-starter依赖。
    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
    • 注意：版本号可以根据实际情况进行调整。

  • 步骤二：配置Swagger

    • 在Spring Boot的主应用类上添加@EnableOpenApi注解，开启Swagger功能。
    • 可以通过创建一个SwaggerConfig类来进行更详细的配置，例如：
    import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
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.your_package_name"))
           .paths(PathSelectors.any())
           .build()
           .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
           .title("Your API Title")
           .description("Your API Description")
           .version("1.0.0")
           .build();
    }
}
    • 这里com.example.your_package_name需要替换为实际包含API接口的包名。通过这个配置类，可以定义API的标题、描述、版本等信息，还可以指定扫描接口的范围。

  • 步骤三：访问Swagger-UI

    • 启动Spring Boot应用后，可以通过http://localhost:8080/swagger-ui.html（默认端口是8080，如果修改了端口需要相应调整）来访问Swagger - UI界面。在这里可以查看API文档，包括接口路径、请求方法、参数、响应等信息，并且可以进行接口测试。

2. 在Node.js项目中（以Express为例）

  • 步骤一：安装Swagger - UI中间件和相关库

    • 在项目目录下，通过命令行安装swagger-ui-express和swagger-jsdoc。
    npm install swagger-ui-express swagger-jsdoc --save

  • 步骤二：配置Swagger文档

    • 创建一个swagger.js（文件名可自定义）文件用于配置Swagger。
    const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: 'Your API Title',
            version: '1.0.0',
            description: 'Your API Description'
        },
        servers: [
            {
                url: 'http://localhost:3000' // 根据实际服务器地址修改
            }
        ]
    },
    apis: ['./routes/*.js'] // 假设API路由文件在routes文件夹下，根据实际情况修改
};

const specs = swaggerJsdoc(options);

module.exports = (app) => {
    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
};
    • 这个配置文件定义了API的基本信息（标题、版本、描述）、服务器地址以及文档的位置（通过apis选项指定包含API接口定义的文件路径）。

  • 步骤三：在主应用文件中引入配置

    • 在app.js（或主应用文件）中引入swagger.js文件。
    const express = require('express');
const app = express();
const swaggerConfig = require('./swagger');

// 其他中间件和路由设置

swaggerConfig(app);

app.listen(3000, () => {
    console.log('Server is running on port 3000');
});
    • 启动Node.js应用后，可以通过http://localhost:3000/api-docs访问Swagger-UI界面来查看和测试API文档。

3. 作为独立的HTML文件（静态部署）

  • 步骤一：下载Swagger - UI资源

  • 步骤二：配置index.html文件

    • 在dist目录下找到index.html文件，打开并修改其中的url参数，用于指向后端API的Swagger JSON文档。例如：
    <!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="swagger-ui.css">
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="swagger-ui-bundle.js"></script>
    <script>
        const ui = SwaggerUIBundle({
            url: "http://your-api-server-url/swagger.json", // 根据实际API地址修改
            dom_id: '#swagger-ui',
            presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIBundle.SwaggerUIStandalonePreset
            ],
            layout: "BaseLayout"
        });
    </script>
</body>
</html>
    • 这里http://your-api-server-url/swagger.json需要替换为后端实际生成的Swagger JSON文档的地址。这个JSON文档包含了API的详细信息，如接口定义、参数、响应等。

  • 步骤三：部署index.html和相关资源文件

    • 将index.html文件和dist目录下的swagger-ui-bundle.js、swagger-ui-css等资源文件部署到Web服务器上。可以通过访问部署后的index.html文件所在的URL来打开Swagger-UI界面并查看API文档。
posted @   软件职业规划  阅读(28)  评论(0)  编辑  收藏  举报
点击右上角即可分享
微信分享提示