浅析如何使用Swagger生成带权限控制的API文档_Java

在咱们的开发工作里，api 文档就像是项目的说明书，清晰准确的文档能让我们的开发效率大幅提升。而当涉及到权限控制时，如何生成既安全又详细的 api 文档就成了一个关键问题。今天，我就和大家好好唠唠如何用 swagger 来生成带有权限控制的 api 文档。

准备工作

咱们做开发，就像行军打仗，工具和资源就是我们的“粮草”。在使用 swagger 生成带权限控制的 api 文档之前，得先把相关的依赖添加到项目里。如果你用的是 maven 项目，在 pom.xml 里加上下面这些依赖：

<dependencies>
    <!-- swagger api 注解 -->
    <dependency>
        <groupid>io.springfox</groupid>
        <artifactid>springfox-swagger2</artifactid>
        <version>2.9.2</version>
    </dependency>
    <!-- swagger ui -->
    <dependency>
        <groupid>io.springfox</groupid>
        <artifactid>springfox-swagger-ui</artifactid>
        <version>2.9.2</version>
    </dependency>
    <!-- spring security -->
    <dependency>
        <groupid>org.springframework.boot</groupid>
        <artifactid>spring-boot-starter-security</artifactid>
    </dependency>
</dependencies>

这些依赖就像是我们的武器装备，有了它们，我们才能在开发的战场上“披荆斩棘”。

配置 swagger

有了依赖，接下来就要对 swagger 进行配置，让它能按照我们的需求生成 api 文档。创建一个 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;
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.controller"))
               .paths(pathselectors.any())
               .build();
    }
}

这里我们指定了要扫描的控制器包路径，这样 swagger 就能知道从哪里获取 api 的信息了。

权限控制

在实际的项目中，api 文档往往包含了很多敏感信息，所以给文档加上权限控制是非常必要的。我们用 spring security 来实现这个功能，创建一个 spring security 配置类：

import org.springframework.context.annotation.bean;
import org.springframework.context.annotation.configuration;
import org.springframework.security.config.annotation.web.builders.httpsecurity;
import org.springframework.security.config.annotation.web.configuration.enablewebsecurity;
import org.springframework.security.core.userdetails.user;
import org.springframework.security.core.userdetails.userdetails;
import org.springframework.security.core.userdetails.userdetailsservice;
import org.springframework.security.provisioning.inmemoryuserdetailsmanager;
import org.springframework.security.web.securityfilterchain;
 
@configuration
@enablewebsecurity
public class securityconfig {
 
    @bean
    public securityfilterchain securityfilterchain(httpsecurity http) throws exception {
        http
               .authorizerequests()
               .antmatchers("/swagger-ui.html", "/swagger-resources/**", "/v2/api-docs").hasrole("admin")
               .anyrequest().authenticated()
               .and()
               .httpbasic();
        return http.build();
    }
 
    @bean
    public userdetailsservice userdetailsservice() {
        userdetails user =
             user.withdefaultpasswordencoder()
               .username("admin")
               .password("password")
               .roles("admin")
               .build();
 
        return new inmemoryuserdetailsmanager(user);
    }
}

在这个配置里，我们规定只有拥有 admin 角色的用户才能访问 swagger ui 和 api 文档相关的路径，就像给文档加上了一把安全锁，只有有钥匙的人才能打开。

给 api 加上权限注解

在控制器的方法上，我们要添加权限注解和 swagger 注解，这样在生成的文档里就能清楚地看到每个 api 的权限要求了：

import io.swagger.annotations.api;
import io.swagger.annotations.apioperation;
import org.springframework.security.access.prepost.preauthorize;
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(value = "示例 api", description = "这是一个带有权限控制的示例 api 文档")
public class examplecontroller {
 
    @getmapping("/hello")
    @apioperation(value = "获取问候语", notes = "需要 admin 角色才能访问")
    @preauthorize("hasrole('admin')")
    public string hello() {
        return "hello, world!";
    }
}

这里用 @preauthorize 注解对方法进行权限控制，同时在 @apioperation 注解的 notes 属性中说明权限要求，就像给每个 api 贴上了一个“使用说明”。

查看文档

当我们完成了以上所有步骤，就可以启动 spring boot 应用程序，然后访问 http://localhost:8080/swagger-ui.html（端口号根据实际情况修改）。这时浏览器会弹出 http basic 认证对话框，输入我们在 securityconfig 中配置的用户名和密码（这里是 admin 和 password），认证通过后就能看到带有权限信息的 api 文档了，就像打开了一扇通往知识宝库的大门。