Swagger 笔记

Swagger 简介#

Open API#

Open API规范(OpenAPl Specification),以前叫做Swagger规范,是REST API的API描述格式。

Open API文件允许描述整个API,包括:

  • 每个访问地址的类型,POST 或 GET。
  • 每个操作的参数。包括输入输出参数。
  • 认证方法。
  • 连接信息,声明,使用团队和其他信息。

Open API规范可以使用YAML 或JSON格式进行编写。这样更利于我们和机器进行阅读。

Swagger#

Swagger是一套围绕Open API规范构建的开源工具,可以帮助设计,构建,记录和使用REST API。

Swagger工具包括的组件:

  • Swagger Editor:基于浏览器编辑器,可以在里面编写ОpenAPI规范。类似 Markdown具有实时预览描述文件的功能。
  • Swagger Ul:将Open API规范呈现为交互式API文档。用可视化U展示描述文件。
  • Swagger Codegen:将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成 html格式和cwiki形式的接口文档,同时也可以生成多种言语的客户端和服务端代码。
  • Swagger Inspector:和Swagger Ul有点类似,但是可以返回更多信息,也会保存请求的实际参数数据。

Springfox#

使用Swagger时如果碰见版本更新或迭代时,只需要更改Swagger的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件(yml或json)也是一定的工作负担,久而久之就直接修改代码,而不去修改描述文件了,这样基于描述文件生成接口文档也失去了意义。

Marty Pitt编写了一个基于Spring的组件 swagger-springmvc。Spring-fox就是根据这个组件发展而来的全新项目。

Spring-fox是根据代码生成接口文档,所以正常的进行更新项目版本,修改代码而不需要跟随修改描述文件。

Spring-fox利用自身AOP特性,把Swagger集成进来,底层还是Swagger。但是使用起来确方便很多。

所以在实际开发中,都是直接使用spring-fox。

Swagger 配置#

pom.xml

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

1、配置基本信息#

@Configuration
public class SwaggerConfig {

    @Bean
    // 创建Docket的bean方法
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())  // 设置具体的摘要信息
                .select()
                .build();
    }

    // 创建存储了摘要信息的APIInfo信息
    public ApiInfo swaggerDemoApiInfo() {
        return new ApiInfoBuilder()
                    .contact(new Contact("百度","http://www.baidu.com", "xx@163.com"))
                    .title("这里是swagger标题")
                    .description("这里是swagger的描述信息")
                    .version("1.0.0")  // 文档的版本信息
                    .build();
    }

}

2、设置扫描的包#

apis():设置扫描的包路径

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(swaggerDemoApiInfo())  
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.baizhi.user.controller"))
        .build();
}

3、自定义注解设置不需要生成接口文档的方法#

3.1 自定义注解#

建立一个包annotation,在下面建一个annotation!类

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger{
}

3.2 添加规则#

apis(not(withMethodAnnotation(NotIncludeSwagger.class))) 可以设置生成规则

  • public static <T> Predicate<T> not(Predicate<T> predicate):表示不允许的条件
  • withMethodAnnotation:表示此注解是方法级别注解。
@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(swaggerDemoApiInfo())  
        .select()
        .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))  // 
        .build();
}

3.3 添加 NotIncludeSwagger 注解#

在不需要生成接口文档的犯法上面添加 @NotIncludeSwagger 注解后,该方法将不会被Swagger进行生成在接口文档中。

@NotIncludeSwagger
@RequestMapping("/userInfo")
public ... {}

4、设置范围(用的不多)#

.paths() 设置满足什么规则的url被生成接口文档,可以用正则表达式进行匹配。

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(swaggerDemoApiInfo())  
        .select()
        .paths(allowPaths())
        .build();
}

public Predicate<String> allowPaths() {
    return or(
        regex("/demo/.*")
    );
}

其中

  • .:在正则表达式中表示任意字符
  • *:表示可以出现n次

Swagger 常用注解#

1、@Api#

@Api 是类上注解。控制整个类生成接口信息的内容。

  • tags:类的名称。可以有多个值,多个值表示多个副本
  • description:描述,已过时。
@RestController
@RequestMapping("/people")
@Api(tags = {"mydemo"}, description = "描述")
public class DemoController {}

2、@ApiOperation#

@ApiOperation:写在方法上,对方法进行总体描述

  • value:接口描述
  • notes:提示信息
@ApiOperation(value = "接口描述", notes = "接口提示信息")
img

3、@ApiParam#

@ApiParam:写在方法参数前面。用于对参数进行描述或说明是否为必填项等说明。

  • name:参数名称(不建议改)
  • value:参数描述
  • required:是否是必须
public People getPeople(Integer id, @ApiParam(value="姓名", required=true) String name, String address)

4、@ApiModel#

@ApiModel:是类上注解,主要应用Model,也就是说这个注解一般都是写在实体类上。

  • value:名称
  • description:描述
@ApiModel(value = "人类", description = "描述")
public class People {}

img

5、@ApiModelProperty#

@ApiModelProperty :可以用在方法或属性上。用于当对象作为参数是定义这个字段的内容。

  • value:名称
  • name:重写属性名
  • required:是否是必须的
  • example:实例内容
  • hidden:是否隐藏
@ApiModelProperty(value = "姓名", name = "name", required = true, example = "zhang'san")
private String name;

img

6、@ApiIgnore#

@Apilgnore用于方法或类或参数上,表示这个方法或类被忽略。和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解,@NotIncludeSwagger是我们自定义的注解。

7、@ApiImplicitParam#

@ApilmplicitParam用在方法上,表示单独的请求参数,总体功能和@ApiParam类似。

  • name:属性名
  • value:描述
  • required:是否是必须的
  • paramType:属性类型
  • dataType:数据类型
@PostMapping("/getPeople")
@ApiImplicitParam(name = "address", value = "地址", required = true, paramType = "query", dataType = "string")
public People getPeople(Integer id, @ApiParam(value = "姓名", required = true)String name, String address)

img

作者:stdxiaozhang

出处:https://www.cnblogs.com/stdxiaozhang/p/17069992.html

版权:本作品采用「署名-非商业性使用-相同方式共享 4.0 国际」许可协议进行许可。

吼吼,如果对你有帮助的话,可以点个赞呀!

posted @   啊哈小张同学  阅读(64)  评论(0编辑  收藏  举报
相关博文:
阅读排行:
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· 清华大学推出第四讲使用 DeepSeek + DeepResearch 让科研像聊天一样简单!
· 实操Deepseek接入个人知识库
· CSnakes vs Python.NET:高效嵌入与灵活互通的跨语言方案对比
· Plotly.NET 一个为 .NET 打造的强大开源交互式图表库
more_horiz
keyboard_arrow_up dark_mode palette
选择主题
menu
点击右上角即可分享
微信分享提示