Swagger详细解释

Swagger作用:

使用

第一步:在pom.xml导入依赖

<dependency><!--添加Swagger依赖 -->
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>	
</dependency>
<dependency><!--添加Swagger-UI依赖 -->
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

第二步:添加配置类(放在config包下)

通过扫描的方式自动生成文档,要配置扫描路径

去扫描controller的类,控制层有swagger需要的请求路径、请求方式、请求参数、响应内容

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))//扫描的包路径
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档的标题")//文档标题
                .version("1.0.0")//文档版本说明
                .build();
    }

}

第三步:在application.yml添加配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

localhost:8080/swagger-ui.html

基本表示

创建学生类控制层,在类和方法上写上对应的信息,会自动显示到swagger文档里

@Api(tags = " ")

这个注解是写在控制层上方,给该控制层做简单表示

 @ApiOperation ,value,notes

该注解是写在方法上,给方法做简单表示,解释默认给value赋值

notes是该方法的一些注意点,多个注解value不可省略

注意Security配置

如果有配置Security,会对swagger进行拦截,需要对它进行配置

swagger请求参数配置1

swagger请求参数配置2

实体类里ApiModel 与 ApiModerProperty

加上注解RequetBody

表示用json的形式传

增强版 knife4j(图形更美观)

使用:

导入依赖

导入这个依赖时,之前导入的那两个依赖可以删掉

他们之间有联系,会一起导入之前的依赖

<!--    使用knife4j可以将swagger的两个依赖删除 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

修改配置

将注解改掉

localhost:8080/doc.html

模拟响应示例

(它是内置postman)

统一设置返回值

如果用返回值map,会识别不出来。

建议自己搞一个类R(里面)返回

package com.example.demo.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

// Result
@ApiModel("响应实体")
public class R<T> {

    @ApiModelProperty("提示消息")
    private String msg;

    @ApiModelProperty("状态码")
    private Integer code;

    @ApiModelProperty("数据")
    private T data;

    public R() {
    }

    public R(String msg, Integer code, T data) {
        this.msg = msg;
        this.code = code;
        this.data = data;
    }

    public static R success() {
        return new R("操作成功！！", 200, null);
    }

    public static <T> R success(T data) {
        return new R("操作成功！！", 200, data);
    }

    public static R error() {
        return new R("操作失败！！", 500, null);
    }

    public static R error(String msg) {
        return new R(msg, 500, null);
    }

    public static R to(int rs) {
        return rs > 0 ? R.success() : R.error();
    }


    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }
}

但这个时候data没有标识出来,要把泛型传进去

一个控制层对应一个分类

设置全局参数token

@ApiReponses和@ApiResponse

(用得较少)