swagger

裴大有

已于 2022-12-21 09:30:57 修改

阅读量2.6k

点赞数 1

分类专栏： swagger 文章标签： java 文档资料

于 2022-12-21 09:26:13 首次发布

本文链接：https://blog.csdn.net/m0_52583051/article/details/128388221

版权

swagger 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

swagger

1 引入依赖

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

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

2 创建配置类

package com.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {

    //配置Swagger的Bean实例
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //显示在ui界面上配置信息
                .apiInfo(apiInfo())

                //是否启用默认状态码     false:不启用
                .useDefaultResponseMessages(false)

                //分组名称(可以创建多个Docket就有多个组名)
                .groupName("product")

                //是否开启Swagger
                .enable(true)

                // 返回 ApiSelectorBuilder
                .select()

                //RequestHandlerSelectors指定扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.product"))

                // 接口过滤方案
                .paths(PathSelectors.any())
                .build();

    }

    //配置API信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //API文档标题
                .title("这是API文档标题")

                //文档简介
                .description("这是文档简介")

                //服务Url
                .termsOfServiceUrl("这是http://www.xxx.com")

                //版本号
                .version("这是版本号1.0.0")

                //联系人
                .contact("这是联系人xxx")

                .build();
    }

}

这里是图片描述在这里插入图片描述

1 ApiInfo

显示在ui界面上的配置信息

version：	API 版本

title：		文档标题

description：文档描述

termsOfServiceUrl：服务Url

license：	许可

licenseUrl：	许可链接

contact：	联系人信息

vendorExtensions：扩展信息

2 ApiSelectorBuilder

构建 Docket 时通过 select() 方法配置怎么扫描接口，它会返回一个 ApiSelectorBuilder 对象

它需要配置的是 requestHandlerSelector 和 pathSelector。

通过 ApiSelectorBuilder#apis() 方法配置(也是链式编程)，在 RequestHandlerSelectors 提供了配置方案：

any()：扫描所有，项目中的所有接口都会被扫描到

none()：不扫描接口

withClassAnnotation()：扫描注解

withMethodAnnotation()：扫描方法上的注解，比如 withMethodAnnotation(GetMapping.class) 只扫描 @GetMapping 标识的 GET 请求

withClassAnnotation()：扫描类上的注解，比如 withClassAnnotation(Controller.class) 只扫描有 @Controller 注解的类中的接口

basePackage()：扫描指定路径，比如 basePackage(“com.test.controller”) 只扫描 controller 包的解耦

常用的是 basePackage()，只扫描 controller 包

3 pathSelector

接口过滤方案

可以过滤掉一些api，让它不出现在文档上。

两种配置方案，一种是 @ApiIgnore 它只能用于单个接口。

另一种就是在 Docket 上增加筛选，Docket 配置的规则，可以对多个接口起过滤作用。

any()：	任何路径都满足条件
none()：	任何路径都不满足条件
regex()：通过正则表达式控制
ant()：	通过 ant 控制

4 groupName

分组,可以创建多个Docket

5 useDefaultResponseMessages

默认状态码

Swagger 默认提供了 200,401,403,404 几种状态码。

可以根据自己需要，决定是否开启或关闭。

6 enable

是否开启Swagger

测试环境中一般需要启动 Swagger，上线的时候一般都会关闭，避免借口暴露的风险。

可以在不同配置文件中做控制。

3 访问地址

2.9.x版本访问地址：

http://localhost:8081/{context-path}/swagger-ui.html

3.0.x版本访问地址

http://localhost:8081/{context-path}/swagger-ui/index.html

例:

http://localhost:8809/product/swagger-ui.html

http://localhost:8809/product/doc.html

4 常用注解

官网简介:

在这里插入图片描述

1 @Api

@Api：接口类说明

    @Api(tags = "demo")
    @RestController
    @RequestMapping("/")
    public class Demo {

    }

一般加在Controller上,表明这个类的作用。

只有带有@Api注释的类才会被Swagger扫描。

在这里插入图片描述

属性

value url的路径值

tags 如果设置这个值、value的值会被覆盖

description 对api资源的描述

basePath 基本路径可以不配置

position 如果配置多个Api 想改变显示的顺序位置

produces For example, “application/json, application/xml”

consumes For example, “application/json, application/xml”

protocols Possible values: http, https, ws, wss.

authorizations 高级特性认证时配置

hidden 配置为true 将在文档中隐藏

2 @ApiOperation

@ApiOperation：接口作用说明

    @ApiOperation(value = "新增商品", notes = "新增商品的描述")
    @PostMapping("/test1")
    public String test1(){
        return "123";
    }

在这里插入图片描述

属性

value url的路径值

tags 如果设置这个值、value的值会被覆盖

notes 借口描述

description 对api资源的描述

basePath 基本路径可以不配置

position 如果配置多个Api 想改变显示的顺序位置

produces For example, “application/json, application/xml”

consumes For example, “application/json, application/xml”

protocols Possible values: http, https, ws, wss.

authorizations 高级特性认证时配置

hidden 配置为true 将在文档中隐藏

response 返回的对象

responseContainer 这些对象是有效的 “List”, “Set” or “Map”.，其他无效

httpMethod “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”

code http的状态码默认 200

extensions 扩展属性

3 @ApiImplicitParams 和 @ApiImplicitParam

@ApiImplicitParam：参数说明

@ApiImplicitParams：一个ApiImplicitParams可以包含多个ApiImplicitParam

    @ApiImplicitParams({
		@ApiImplicitParam(name="a",value="这是参数a",required=true,paramType="query",
                          dataType = "String",defaultValue = "默a认值"),
		@ApiImplicitParam(name="b",value="这是参数b",required=true,paramType="form"),
		@ApiImplicitParam(name="c",value="这是参数c",required=true,paramType="query",
                          dataType = "String",defaultValue = "默c认值"),
		@ApiImplicitParam(name="d",value="这是参数d",required=false,paramType="form",
                          defaultValue = "默d认值")
    })
    @ApiOperation(value = "入参说明", notes = "接口描述")
    @PostMapping("/test2")
    public String test2(@RequestParam String a, @RequestParam String b,
                        @RequestParam String c, @RequestParam String d){
        return null;
    }

在这里插入图片描述

默认值（defaultValue）这个属性，如果给定了值，那么会在Swagger文档中的调试里出现的。

属性

name 参数名

value 参数的说明、描述

required 参数是否必须必填

paramType 参数放在哪个地方

query --> 请求参数的获取：@RequestParam

header --> 请求参数的获取：@RequestHeader

path（用于restful接口）–> 请求参数的获取：@PathVariable

body（请求体）–> @RequestBody User user

form（普通表单提交）

dataType 参数类型，默认String，其它值dataType=“Integer”

defaultValue 参数的默认值

4 @ApiParam

@ApiParam：加在参数前面，用来表明参数的作用

    @ApiOperation("查询商品信息")
    @PostMapping("/queryGoodsInfo")
    public String queryUserInfo(
		@ApiParam("商品名称") @PathParam("commodityName") String commodityName,
		@ApiParam("商品编码") @PathParam("commodityCode") String commodityCode){
        return null;
    }

在这里插入图片描述

属性

name 属性名称

value 属性值

defaultValue 默认属性值

allowableValues 可以不配置

required 是否属性必填

access 不过多描述

allowMultiple 默认为false

hidden 隐藏该属性

example 举例

5 @ApiModel 和 @ApiModelProperty

@ApiModel：加在实体类上

@ApiModelProperty：加在属性上

当使用这个实体作为接收参数对象时，swagger文档上就会显示这个类的信息

@ApiModel(value = "用户实体", description = "描述")
public class UserDto {

    @ApiModelProperty(value = "主键id", required = true)
    private Long id;

    @ApiModelProperty(value = "名字", required = true)
    private String name;

    @ApiModelProperty(value = "年龄", required = true)
    private Integer age;

    @ApiModelProperty(value = "邮箱", required = true)
    private String email;

    @ApiModelProperty(value = "创建时间", required = false)
    private Date createTime;

    @ApiModelProperty(value = "更新时间", required = false)
    private Date updateTime;
    
}

在这里插入图片描述

属性

value 属性简要描述

name 属性名

allowableValues 长度

access 允许从api文件中过滤属性

notes 注释说明

dataType 参数数据类型

required 是否可以为空，默认false

position 属性排序

hidden 允许隐藏

example 属性示例