Swagger

最新推荐文章于 2025-06-16 16:13:01 发布

原创最新推荐文章于 2025-06-16 16:13:01 发布 · 156 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#lua #开发语言

1 介绍

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

2 使用

1 导入依赖

<!--        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>

2 创建Swagger配置类

在config的包下创建配置类SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        // 构建swagger页面信息
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("EMOS在线办公系统")
                .description("简单方便的办公系统")
                .termsOfServiceUrl("http://127.0.0.1:8080")
                .version("v1.0")
                .build();

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .paths(PathSelectors.any())  //扫描所有路径
                //使用@ApiOperation的方法会被提取到REST API中
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();

        /*
         * 下面的语句是开启对JWT的支持，当用户用Swagger调用受JWT认证保护的方法，
         * 必须要先提交参数（例如令牌）
        */
        //存储用户必须提交的参数
        List<ApiKey> apiKeyList = new ArrayList<>();
        //规定用户需要输入什么参数
        ApiKey apiKey = new ApiKey("token", "token", "header");
        apiKeyList.add(apiKey);
        docket.securitySchemes(apiKeyList);

        //如果用户JWT认证通过，则在Swagger中全局有效
        AuthorizationScope scope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] scopes = {scope};
        //存储令牌和作用域
        SecurityReference reference = new SecurityReference("token", scopes);
        List<SecurityReference> refList = new ArrayList<>();
        refList.add(reference);
        SecurityContext context = SecurityContext.builder().securityReferences(refList).build();
        List<SecurityContext> cxtList = new ArrayList<>();
        cxtList.add(context);
        docket.securityContexts(cxtList);
        return docket;
    }
}

编写controller测试

@RestController
@RequestMapping("/test")
@Api("测试Web接口")
public class TestController {

    @GetMapping("/sayHello")
    @ApiOperation("最简单的测试方法")
    public R sayHello(Action action) {
        return R.ok().put("message", "HelloWorld").put("action",action);
    }
}

启动项目，访问

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

3 注解说明

@Api：用在Controller控制器类上
     属性tags="说明该类的功能及作用"

@ApiOperation：用在Controller控制器类的请求的方法上
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：请求方法中参数的说明
        name：参数名
        value：参数的汉字说明、解释、用途
        required：参数是否必须传，布尔类型
        paramType：参数的类型，即参数存储位置或提交方式
            · header --> Http的Header携带的参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam   （如上面的例子）
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在控制器的请求的方法上，对方法的响应结果进行描述
    @ApiResponse：用于表达一个响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：响应结果封装类，如上例子中的AjaxResponse.class

@ApiModel：value=“通常用在描述@RequestBody和@ResponseBody注解修饰的接收参数或响应参数实体类”
    @ApiModelProperty：用在实体类的属性上，value="实体类属性的描述"

注意：

报错：Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

可以降低boot版本，或者在配置文件中添加

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER