Swagger+Rest接口

最新推荐文章于 2023-03-21 20:33:37 发布

21秋招拒做分母

最新推荐文章于 2023-03-21 20:33:37 发布

阅读量476

点赞数

分类专栏： Spring 文章标签： swagger2

本文链接：https://blog.csdn.net/qq_43378019/article/details/113482184

版权

Spring 专栏收录该内容

4 篇文章 0 订阅

订阅专栏

Springfox

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

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

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

　　Spring-fox 利用自身 AOP 特性，把 Swagger 集成进来，底层还是Swagger。但是使用起来确方便很多。所以在实际开发中，都是直接使用 spring-fox。

springfox快速使用：

1、编写一个SpringBoot项目，勾选web下的spring web，创建people类，和一个controlle

package com.soldier.pojo;

/**
 * @Author soldier
 * @Date 2020/3/11 11:18
 * @Version 1.0
 * @Description:
 */
public class People {
    private Long id;
    private String name;
    private String address;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}
package com.soldier.controller;

import com.soldier.pojo.People;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Author soldier
 * @Date 2020/3/11 11:19
 * @Version 1.0
 * @Description:
 */
@RestController
@RequestMapping("/people")
public class DemoController {

    @RequestMapping("/getPeople")
    public People getPeople(Long id, String name) {
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("南宁");
        return people;
    }
}

2、导入spring-box依赖

<!--spring-fox依赖-->
<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>

3、启动类添加@EnableSwagger2注解

4、启动项目，访问Swagger UI

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

Swagger UI的使用

　　· 访问 swagger-ui.html 后可以在页面中看到所有需要生成接口文档的控制器名称。

　　· 每个控制器中间包含多所有控制器方法的各种访问方式。如果使用的是@RequestMapping 进行映射，将显示下面的所有请求方式。如果使用@PostMapping 将只有 Post 方式可以能访问，下面也就只显示 Post 的一个。

　　· 点击某个请求方式中 try it out

　　· 会出现界面要求输入的值。输入完成后点击 Execute 按钮

　　· 下面会出现 Request URL 已经不同状态码相应回来的结果：

Swagger的配置

　　可以在项目中创建 SwaggerConfig，进行配置文档内容。

1、配置基本信息

　　Docket：摘要对象，通过对象配置描述文件的信息。 apiInfo:设置描述文件中 info。参数类型 ApiInfo

　　select()：返回 ApiSelectorBuilder 对象，通过对象调用 build()可以创建 Docket 对象

　　ApiInfoBuilder：ApiInfo 构建器。

项目中新建一个配置类：

package com.soldier.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @Author soldier
 * @Date 2020/3/11 11:42
 * @Version 1.0
 * @Description: Swagger配置
 */
@Configuration
public class SwaggerConfig {

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

    private ApiInfo swaggerDemoApiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact("百度", "www.baidu.com", "baidu@163.com"))
                // 标题
                .title("这是Swagger的标题")
                // 描述
                .description("这是Swagger的描述")
                // 版本
                .version("1.0.0")
                .build();
    }
}

重启项目，访问【http://localhost:8080/swagger-ui.html】，效果如下：

2、设置扫描的包

　　可以通过 apis()方法设置哪个包中内容被扫描

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

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

　　1）自定义注解，名称可以随便取

package com.soldier.interfaceDemo;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * @Author soldier
 * @Date 2020/3/11 12:11
 * @Version 1.0
 * @Description: 自定义注解
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger {
}

　2）添加规则

　　　　通过 public ApiSelectorBuilder apis(Predicate<RequestHandler> selector)可以设置生成规则。

　　　　public static <T> Predicate<T> not(Predicate<T> predicate) :表示不允许的条件。

　　　　withMethodAnnotation：表示此注解是方法级别注解。

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(swaggerDemoApiInfo())
           .select()
//         .apis(RequestHandlerSelectors.basePackage("com.soldier.controller"))
           // 自定义注解设置不需要生成接口文档的方法
           .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
           .build();
}

　　3）添加 @NotIncludeSwagger 注解

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

@NotIncludeSwagger
@RequestMapping("/getPeople2")
public People getPeople2(Long id, String name, String address) {
    People people = new People();
    people.setId(id);
    people.setName(name);
    people.setAddress(address);
    return people;
}

　　　　添加 @NotIncludeSwagger 前的：

　　　　添加 @NotIncludeSwagger 后的效果：

4、设置范围

　　通过 public ApiSelectorBuilder paths(Predicate<String> selector) 可以设置满足什么样规则的 url 被生成接口文档。可以使用正则表达式进行匹配。

　　下面例子中表示只有以/demo/开头的 url 才能被 swagger 生成接口文档：

　　如何希望全部扫描可以使用 paths(PathSelectors.any())

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(swaggerDemoApiInfo())
           .select()
//         .apis(RequestHandlerSelectors.basePackage("com.soldier.controller"))
           // 自定义注解设置不需要生成接口文档的方法
//         .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
           // 设置范围：以/demo/开头的 url 才能被 swagger 生成接口文档
           // 如何希望全部扫描可以使用 paths(PathSelectors.any())
           .paths(allowPaths())
           .build();
}

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

四、Swagger2 常用注解

　　1）Api

　　@Api 是类上注解。控制整个类生成接口信息的内容。 tags：类的名称可以有多个值多个值表示多个副本，description:描述已过时。

@RestController
@RequestMapping("/people")
@Api(tags = {"myDemo"}, description = "DemoController描述")
public class DemoController {}

　　在swagger-ui.html 显示的效果：

　　2）ApiOperation

　　@ApiOperation 写在方法上，对方法进行总体描述--》value：接口描述，notes：提示信息

@RequestMapping("/getPeople")
@ApiOperation(value = "接口描述", notes = "提示信息")

　　页面效果：

　　3）ApiParam

　　@ApiParam 写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明--》name：参数名称，value：参数描述，required：是否是必须

@RequestMapping("/getPeople")
@ApiOperation(value = "接口描述", notes = "提示信息")
public People getPeople(Long id, @ApiParam(value = "姓名 这个是参数描述", required = true) String name) {}

　　页面效果：

　　4）ApiModel

　　@ApiModel 是类上注解，主要应用 Model，也就是说这个注解一般都是写在实体类上--》value：名称，description：描述

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

　　在swagger-ui.html 显示的效果：

　　5）ApiModelProperty

　　@ApiModelProperty 可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容--》value：描述，name：重写属性名，required：是否是必须的，example：示例内容，hidden：是否隐藏。

@ApiModelProperty(value = "描述:姓名", name = "重写属性名:name", required = true, example = "张三")
private String name;

　　页面效果：

　　6）ApiIgnore

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

　　7）ApiImplicitParam

　　@ApiImplicitParam 用在方法上，表示单独的请求参数，总体功能和@ApiParam 类似--》name：属性名，value：描述，required：是否是必须的，paramType：属性类型，dataType：数据类型

@RequestMapping("/getPeople2")
@ApiImplicitParam(name = "address",value = "地址",required = true,paramType = "query",dataType = "string")
public People getPeople2(Long id, String name, String address) {}

　　页面效果：

　　如果希望在方法上配置多个参数时，使用 @ApiImplicitParams 进行配置。示例如下：

@RequestMapping("/getPeople2")
@ApiImplicitParams(value={
       @ApiImplicitParam(name="id",value = "编号",required = true),
       @ApiImplicitParam(name="name",value = "姓名",required = true)
})
public People getPeople2(Long id, String name, String address) {}

　　页面效果：