为了账号安全,请及时绑定邮箱和手机立即绑定

如何在SpringBoot中快速整合Swagger?

2021.04.16 16:11 779浏览

一、传统的Swagger配置方式

开发前后端分离或者微服务项目,调试后端Web接口必然会用到Swagger,特别是给Swagger添加上JWT的时候,配置代码写起来较为复杂和啰嗦。例如下面的这个配置类,就是给SpringBoot设置Swagger,并且附带上JWT,一堆集合,看着就让人头晕。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfoBuilder builder = new ApiInfoBuilder();
        builder.title("EMOS在线办公系统");
        ApiInfo info = builder.build();
        docket.apiInfo(info);

        ApiSelectorBuilder selectorBuilder = docket.select();
        selectorBuilder.paths(PathSelectors.any());
        selectorBuilder.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class));
        docket = selectorBuilder.build();

        ApiKey apiKey = new ApiKey("token", "token", "header");
        List<ApiKey> apiKeyList = new ArrayList<>();
        apiKeyList.add(apiKey);
        docket.securitySchemes(apiKeyList);

        AuthorizationScope scope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] scopes = {scope};
        SecurityReference reference = new SecurityReference("token", scopes);
        List refList = new ArrayList();
        refList.add(reference);
        SecurityContext context = SecurityContext.builder().securityReferences(refList).build();
        List cxtList = new ArrayList();
        cxtList.add(context);
        docket.securityContexts(cxtList);

        return docket;
    }
}

二、简化的配置方式

现在SpringDoc整合了Swagger,并且提供了非常简洁的整合方式,创建一个配置类,定义几个注解,Swagger就配置好了,非常的简单。

首先我们要在pom.xml文件中添加SpringDoc的依赖库,如下:

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-spring-boot-2-webmvc</artifactId>
    <version>3.1.5</version>
</dependency>

然后在SpringBoot的yml文件中,简单定义SpringDoc的基本设置

springdoc:
  api-docs:
    enabled: true
    path: /doc-api.html
  swagger-ui:
    path: /swagger-ui.html
    disable-swagger-default-url: on

然后创建一个配置类,内容可以这样写:

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;


@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "emos-api",
                description = "Emos管理系统的后端Java项目",
                version = "1.0"
        )
)
@SecurityScheme(
        name = "Token",
        type = SecuritySchemeType.HTTP,
        bearerFormat = "JWT",
        scheme = "bearer"
)
public class SwaggerConfig {

}

其中@SecurityScheme注解定义的是JWT部分,也就是说,一会儿我们在Swagger页面上可以看到Authorize按钮,我们可以设置HTTP请求头上传的JWT令牌。当然了,其中请求头的名字叫做Token,如果你后端的JWT要求的请求头名字不叫做这个,你可以在上面的注解中修改name属性。

三、写个测试程序

我们随便定义一个Controller,然后声明Web方法,一会我们通过SpringDoc在线测试一下Web方法。例如Web方法接收的数据需要做后端验证,那么我们先要导入后端验证的依赖库,先写一下pom.xml文件。

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-validation</artifactId>
</dependency>

接收Web请求提交的数据,我们要创建一个Form类,Form类的另一个好处是可以写注解做后端验证。

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;

@Data
@Schema(description = "检验登陆验证码")
public class CheckCodeForm {
    @NotBlank(message = "code不能为空")
    @Schema(description = "code")
    private String code;
}

下面编写一个Controller类,然后创建Web方法

@RestController
@RequestMapping("/user")
@Tag(description = "用户Web接口")
public class UserController {

    @PostMapping("/checCode")
    @Operation(summary = "检测登陆验证码")
    public R checCode(@Valid @RequestBody CheckCodeForm form) {
        return R.ok().put("result", true);
    }
}

上面的R类只是个封装响应数据的类而已,先导入依赖库,然后编写代码:

<dependency>
	<groupId>org.apache.httpcomponents</groupId>
	<artifactId>httpcore</artifactId>
	<version>4.4.13</version>
</dependency>
import org.apache.http.HttpStatus;

import java.util.HashMap;
import java.util.Map;

public class R extends HashMap<String, Object> {
    public R() {
        put("code", HttpStatus.SC_OK);
        put("msg", "success");
    }

    public R put(String key, Object value) {
        super.put(key, value);
        return this;
    }

    public static R ok() {
        return new R();
    }

    public static R ok(String msg) {
        R r = new R();
        r.put("msg", msg);
        return r;
    }

    public static R ok(Map<String, Object> map) {
        R r = new R();
        r.putAll(map);
        return r;
    }

    public static R error(int code, String msg) {
        R r = new R();
        r.put("code", code);
        r.put("msg", msg);
        return r;
    }

    public static R error(String msg) {
        return error(HttpStatus.SC_INTERNAL_SERVER_ERROR, msg);
    }

    public static R error() {
        return error(HttpStatus.SC_INTERNAL_SERVER_ERROR, "未知异常,请联系管理员");
    }
}

运行SpringBoot项目,然后访问项目的SpringDoc页面,网址为http://localhost:8080/项目名称/swagger-ui.html,然后浏览器就能看到下面的内容

图片描述
选中我们我测试执行的Web方法,执行在线的测试。因为该Web方法没有设置授权和登陆验证,所以不需要输入Token令牌,直接可以测试,结果如下
图片描述
可以看到Web方法成功运行了,这么看来利用SpringDoc来替代原始的Swagger,的确非常的简单。

点击查看更多内容

本文原创发布于慕课网 ,转载请注明出处,谢谢合作

2人点赞

若觉得本文不错,就分享一下吧!

评论

相关文章推荐

正在加载中
意见反馈 帮助中心 APP下载
官方微信

举报

0/150
提交
取消