SpringBoot 项目配置 Swagger 接口api 搭建 REST

小鱼儿 2023-01-19 07:06 5阅读 0赞

一、简述  
开发前后端分离架构的项目，往往调试后端Web接口需要用到POSTMAN工具。虽然POSTMAN工具的功能非常强大，但是请求参数很多的情况下，我们手写这些参数和数据还是非常麻烦的。因此我们需要一个调试后端Web接口更加简便的方法。恰好Swagger提供了RESTAPI调用方式，我们不需要借助任何工具的情况下，访问Swagger页面，就可以对Web接口进行调用和调试，这种调试方式的效率要远超POSTMAN软件。

二、pom.xml中导入Swagger的依赖

<dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger2</artifactId>
    	<version>2.9.2</version>
    </dependency>
    <dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger-ui</artifactId>
    	<version>2.9.2</version>
    </dependency>

### 三、创建Swagger的配置类 ###

@Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
        //java项目www.fhadmin.org
        @Bean
        public Docket createRestApi() {
            Docket docket = new Docket(DocumentationType.SWAGGER_2);
    
            // ApiInfoBuilder 用于在Swagger界面上添加各种信息
            ApiInfoBuilder builder = new ApiInfoBuilder();
            builder.title("XXXX系统");
            ApiInfo apiInfo = builder.build();
            docket.apiInfo(apiInfo);
    
            // ApiSelectorBuilder 用来设置哪些类中的方法会生成到REST API中
            ApiSelectorBuilder selectorBuilder = docket.select();
            selectorBuilder.paths(PathSelectors.any()); //所有包下的类
            //使用@ApiOperation的方法会被提取到REST API中
            selectorBuilder.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class));
            docket = selectorBuilder.build();
            /*
             * 下面的语句是开启对JWT的支持，当用户用Swagger调用受JWT认证保护的方法，
             * 必须要先提交参数（例如令牌）
             */
            //存储用户必须提交的参数
            List<ApiKey> apikey = new ArrayList();
            //规定用户需要输入什么参数
            apikey.add(new ApiKey("token", "token", "header"));
            docket.securitySchemes(apikey);
    
            //如果用户JWT认证通过，则在Swagger中全局有效
            AuthorizationScope scope = new AuthorizationScope("global", "accessEverything");
            AuthorizationScope[] scopeArray = {scope};
            //存储令牌和作用域
            SecurityReference reference = new SecurityReference("token", scopeArray);
            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;
        }
    }

### 四、测试Web接口 ###

package com.gaoyang.emos.wx.controller;
    import com.gaoyang.emos.wx.common.util.ResponseResult;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    
    //java项目www.fhadmin.org
    @RestController
    @RequestMapping("/test")
    @Api("测试Web接口")
    public class TestController {
        @RequestMapping("testSwagger")
        @ApiOperation("测试Swagger配置")
        public ResponseResult testSwagger(){
            return ResponseResult.error(200,"OK");
        }
    }

![wAAACH5BAEKAAAALAAAAAABAAEAAAICRAEAOw==][wAAACH5BAEKAAAALAAAAAABAAEAAAICRAEAOw]

五、访问swagger-ui.html页面  
注意：还需要添加在启动类中添加 @EnableSwagger2 注解，，否则会出线，页面加载失败情况！

启动项目之后，访问: http://localhost:8080/emos-wx-api/swagger-ui.html

[wAAACH5BAEKAAAALAAAAAABAAEAAAICRAEAOw]: