Spring Boot打造安全可信OpenAPI生态，一键构建API文档和授权系统

2024-01-01 01:40:40

Spring Boot与Swagger：携手构建安全可信的OpenAPI生态系统

引言

在现代化API开发中，Spring Boot和Swagger无疑是不可或缺的强大组合，它们协力简化API文档创建、实现API安全授权，以及构建一个可靠的OpenAPI生态系统。本文将深入探讨Spring Boot与Swagger的相遇，揭示它们如何赋能API开发之旅。

集成Swagger，解锁API文档

引入Swagger依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

配置Swagger：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot Swagger API")
                .description("Spring Boot Swagger API Description")
                .version("1.0")
                .build();
    }
}

访问API文档：

启动项目后，访问http://localhost:8080/swagger-ui.html，即可查看生成的API文档。

安全授权，守护API安全

添加安全定义：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Arrays.asList(new ApiKey("Authorization", "header", "Authorization")));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot Swagger API")
                .description("Spring Boot Swagger API Description")
                .version("1.0")
                .build();
    }
}

添加安全要求：

@RestController
@RequestMapping("/api")
public class ApiController {

    @ApiOperation(value = "获取用户信息", notes = "需要用户授权")
    @RequestMapping(value = "/user", method = RequestMethod.GET)
    public User getUser() {
        //省略代码...
    }
}

现在，需要授权的API访问，请求头必须携带Authorization信息。

OpenAPI框架，赋能API生态

导出OpenAPI文档：

@RestController
@RequestMapping("/api")
public class ApiController {

    @ApiOperation(value = "获取用户信息", notes = "需要用户授权")
    @RequestMapping(value = "/user", method = RequestMethod.GET)
    public User getUser() {
        //省略代码...
    }

    @RequestMapping(value = "/openapi.json", method = RequestMethod.GET)
    public OpenAPI getOpenAPI() {
        return new Swagger2MarkupConverter().from(new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()).build();
    }
}