Swagger集成

最新推荐文章于 2024-05-16 15:30:42 发布

麦客*风之韵

最新推荐文章于 2024-05-16 15:30:42 发布

阅读量31

点赞数

分类专栏： springboot从搭建到集成文章标签： java spring intellij-idea junit

本文链接：https://blog.csdn.net/weixin_40208374/article/details/133345767

版权

springboot从搭建到集成专栏收录该内容

11 篇文章 0 订阅

订阅专栏

集成方式：

检测spring的web请求信息，生成检测结果（json格式）。

根据springfox-swagger2生成的数据，生成可视化的友好页面。

升级到knife4j，生成可视化的友好页面。方式三不能与方式一、二共存，必须注释掉，否则报错。

Pom.xml添加依赖

不同的方式选择不同的依赖，不可全部粘贴

<!--swagger集成方式一-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>


<!--swagger集成方式二-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>


<!--swagger升级方式三-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

配置代码

Springfox提供Docket对象，为其设置相关属性，将其注册成为spring的bean后，可以在接口文档中展示（可配置多个Docket的bean，对应不同分组的接口）。

@Configuration
@EnableSwagger2
public class Swagger2Conf {
    @Bean
    public Docket getUserDocket(){
        ApiInfo apiInfo=new ApiInfoBuilder()
                .title("用户管理")//api标题
                .description("用户管理相关接口描述")//api描述
                .version("1.0.0")//版本号
                .contact("sabre")//本API负责人的联系信息
                .build();
        return new Docket(DocumentationType.SWAGGER_2)//文档类型（swagger2）
                .apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息
                .select()//启动用于api选择的构建器
                 .apis(RequestHandlerSelectors.basePackage("com.test.controller"))//扫描接口的包
                .paths(PathSelectors.any())//路径过滤器（扫描所有路径）
                .build();
    }
}

有时候会存在model显示在接口文档最下面，如下图所示：

去除model需要在配置文件加入如下代码：

@Bean
public UiConfiguration uiConfig() {
    return UiConfigurationBuilder.builder()
            .deepLinking(true)
            .displayOperationId(false)
            // 隐藏UI上的Models模块
            .defaultModelsExpandDepth(-1)
            .defaultModelExpandDepth(0)
            .defaultModelRendering(ModelRendering.EXAMPLE)
            .displayRequestDuration(false)
            .docExpansion(DocExpansion.NONE)
            .filter(false)
            .maxDisplayedTags(null)
            .operationsSorter(OperationsSorter.ALPHA)
            .showExtensions(false)
            .tagsSorter(TagsSorter.ALPHA)
            .validatorUrl(null)
            .build();
}

访问展示

方式一访问链接

http://地址:端口/应用名/v2/api-docs

如：http://127.0.0.1:8086/console/v2/api-docs，返回的是一个json

方式二访问链接

http://地址:端口/应用名/swagger-ui.html

例如：http://127.0.0.1:8086/console/swagger-ui.html#/

方式三访问链接：

http://地址:端口/应用名/doc.html

例如：http://127.0.0.1:8086/console/doc.html

Swagger注解

主要注解简介

@API: 请求类的说明

@ApiOperation: 方法的说明

@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明

@ApiResponses,@ApiResponse: 方法返回值的说明

@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息

@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义

注解应用

控制层中使用的注解

@API(tags="用户模块")
@Controller
public class UserController {
    @ApiOperation("获取用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name="userId",  dataType="String", required=true, value="用户 Id")
    })
    @ApiResponses({
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @ResponseBody
    @RequestMapping("/list")
    public JsonResult list(@RequestParam String userId) {
        ...
        return JsonResult.ok().put("page", pageUtil);
    }
}

实体类中使用的注解

@ApiModel(value = "BannerDTO对象", description = "Banner管理展示实体")
public class BannerDTO implements Serializable {
@JsonFormat(pattern="yyyy-MM-dd",timezone="GMT+8")
@ApiModelProperty(value = "起始时间", required = true, position = 2)
private Date bannerStartTime;


    @ApiModelProperty("标题")
    private String title;
}