• 周六. 7月 2nd, 2022

5G编程聚合网

5G时代下一个聚合的编程学习网

热门标签

Swagger的简单使用

admin

11月 28, 2021

相关包的引入:

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

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

一、应用在参数上

使用@ApiParam注解,如下:

    @ApiOperation(value = "根据id删除数据记录", notes = "逻辑删除数据")
    @DeleteMapping("/remove/{id}")
    public boolean removeById(
            @ApiParam(value = "数据id", example = "100", required = true)
            @PathVariable Integer id) {
        return integralGradeService.removeById(id);
    }

value为页面显示解释,example为实例值

二、应用在方法接口上

使用@ApiOperation注释,实例同上

三、应用在Controller类上

使用@Api注释:

@Api(tags = "积分等级管理")
@CrossOrigin
@RestController
@RequestMapping("/admin/core/integralGrade")
public class AdminIntegralGradeController {
    ...
}        

四、接口文档分类

由于同一系统可能有很多部分的对外接口,比如分成对普通用户的web功能部分的接口,对管理员的管理功能部分的接口。

这需要我们自己新建一个配置类:

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket apiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("AdminApi")
                .select()
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }
    ...
}        

需要添加@EnableSwagger2,在Bean中.groupName("AdminApi")配置选项名字,.paths(Predicates.and(PathSelectors.regex("/admin/.*")))配置该选项所对应的接口路径,这个路径是请求路径。

五、配置文档title

默认的文档标头如下,可读性差。因此,需要配置详细的描述,让阅读者了解这是哪个部分的接口功能。

依然是上述的配置文件:

    private ApiInfo adminApiInfo(){
        return new ApiInfoBuilder()
                .title("SRB后台管理系统API文档")
                .description("本文档描述了SRB后台管理系统的各个模块的接口的调用方式")
        .version("1.3")
        .contact(new Contact("Flynn","baidu.com","[email protected]"))
        .build();
    }

新增配置方法,返回ApiInfo对象,分别配置title名、描述、版本号、作者联系方式,再在上面的配置Bean中加入这个配置(第五行):

    @Bean
    public Docket apiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("AdminApi")
                .apiInfo(adminApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }

发表评论

您的电子邮箱地址不会被公开。