Swagger简介

Swagger是一个流行的RESTful API文档和交互式界面生成工具。它允许开发者轻巧松创建、测试和文档化API。" src="/uploads/images/YUra8Y4A.webp"/>

准备干活

在开头之前， 请确保你的Debian系统已经安装了以下依赖项：

• Node.js和npm
• Java
• Maven或Gradle

sudo apt update
sudo apt install -y nodejs npm openjdk-8-jdk maven

安装Swagger依赖

对于Spring Boot项目，你能用Maven或Gradle来添加Swagger依赖项。

用Maven

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

用Gradle

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

配置Swagger

在Spring Boot项目中，你需要创建一个配置类来启用Swagger并指定要扫描的包。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api {
        return new Docket
                .select
                .apis)
                .paths)
                .build;
    }
}

启动项目并访问Swagger UI

启动你的Spring Boot应用程序后 在浏览器中访问以下URL：

http://localhost:8080/swagger-ui.html

你得能够看到Swagger UI界面其中展示了你的API文档。

高大级配置

Swagger给了许许多高大级配置选项， 比方说自定义UI、添加认证、定义全局参数等。

自定义UI

import springfox.documentation.oas.models.OpenAPI;
import springfox.documentation.oas.models.info.Info;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api {
        return new Docket
                .select
                .apis)
                .paths)
                .build
                .apiInfo);
    }
    private OpenAPI apiInfo {
        return new OpenAPI
                .info.title
                        .version
                        .description);
    }
}

添加认证

import springfox.documentation.builders.SecurityBuilder;
import springfox.documentation.plugins.Docket;
import springfox.documentation.security.SecurityScheme;
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api {
        return new Docket
                .select
                .apis)
                .paths)
                .build
                .securitySchemes));
    }
    private SecurityScheme securityScheme {
        return new ApiKey;
    }
}

Swagger API文档。Swagger是一个有力巨大的工具，能帮你搞优良API的可维护性和可用性。希望这篇文章能够帮你更优良地用Swagger。

---