Swagger笔记

Swagger简介

• 前后端分离的产物
• 用于协调前后端的问题，发现问题能及时解决，免得问题集中爆发
• 好处(百度)：
  1：号称世界上最流行的API框架
  2：Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
  3：直接运行，在线测试API
  4：支持多种语言 （如：Java，PHP等）
• 官网：https://swagger.io/

springboot集成swagger

注意点

使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

使用springboot-web项目进行测试

依赖

swagger-ui和swagger2

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>


        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

配置类

Swagger

@Configurtion
public class SwaggerConfig {}

在主类上开启注解支持
@EnableSwagger2

测试运行

测试网站：http://localhost:8080/swagger-ui.html
结果：

Swagger配置

1:更改默认信息

在SwaggerConfig配置类中进行配置

	@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());

    }
    public ApiInfo apiInfo(){
    	//作者信息
        Contact contact = new Contact("庄忠旺", "链接url", "1935912115@qq.com");
        return new ApiInfo(
                "旺桑",    //题目
                "每日一问：李汀加你了吗",    //描述
                "1",   //版本号
                "urn:tos",  //链接
                contact, //作者信息
                "Apache 2.0", //开源版本号
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
       );
    }

2 配置扫描接口

1 构建Docket时通过select()方法配置怎么扫描接口。

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
//                any()  扫描所有，项目中的所有接口都会被扫描到
//                none()  不扫描接口
                // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
//                    withMethodAnnotation(final Class<? extends Annotation> annotation)
                // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
//                withClassAnnotation(final Class<? extends Annotation> annotation)
//                basePackage(final String basePackage)根据包路径扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.sun.config.hello"))
                // 配置如何通过path过滤,即这里只扫描请求以/h开头的接口
                .paths(PathSelectors.ant("/h/**"))
                .build();
    }

2：过滤接口

这里是扫描com.sun.controller这个包，然后只扫描请求以/a1开头的接口

  @Bean
    public Docket docket(Environment environment){
        
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("d")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sun.controller"))
                // 配置如何通过path过滤,即这里只扫描请求以/a1开头的接口
                .paths(PathSelectors.ant("/h3/**"))
                .build();
    }

结果：

配置Swagger开关

如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

  @Bean
    public Docket docket(Environment environment){

        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev","test");
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean b = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("d")
                .apiInfo(apiInfo())
//                如果为false，就不使用swagger
                .enable(b)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sun.controller"))
                // 配置如何通过path过滤,即这里只扫描请求以/a1开头的接口
//                .paths(PathSelectors.ant("/h3/**"))
                .build();

    }

这里不做配置，用默认的环境进行测试，如果不是**“dev”,“test”**环境，就会访问不到

配置实体类

pijo

public class User {
    public String name;

    public String pwd;
}

controller
返回一个User对象和Swagger进行关联

 @GetMapping("/a1")
    public User h2(){
        return new User();
    }

进行测试

API分组

在配置类中简单配置

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("a");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("b");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("c");
    }
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("d");
    }

配置成功之后有4个分组

API注释(生成文档)

实体类注释

pojo

@ApiModel("用户实体类") //中文注释，放在类上，说明这是一个用户实体类
public class User {

    @ApiModelProperty("姓名")   //中文注释，放在属性上，说明这是一个这是一个什么参数
    public String name;
    @ApiModelProperty("密码")
    public String pwd;
}

结果：

接口注释

@ApiOperation("h3控制类")  //中文注释，放在类上，说明这是h3的控制类类
    @GetMapping("/h3")
    public String h3(@ApiParam("用户名") String name){  //@ApiParam("用户名") 中文注释，放在参数前面，说明传的这个传输为用户名
        return "hello"+name;
    }

结果

Swagger测试(最重要的功能)

测试get

测试代码

@GetMapping("/h1")
    public String h1(){
        return "hello";
    }

无参请求：

1:每一个请求都有一个try it out 点击就可以进行测试了

这里以a1为例，由于没有参数，所以直接请求了，200代表成功

get请求

测试代码：
注意：这里ApiImplicitParam里面的name=参数 要和方法定义的一致

@ApiImplicitParams(
            @ApiImplicitParam(name="username",required=true,dataType="String",paramType="query")
    )
    @ApiOperation("h3控制类")  //中文注释，放在类上，说明这是h3的控制类类
    @GetMapping("/h3")
    public String h3(@ApiParam("用户名") String username){  //@ApiParam("用户名") 中文注释，放在参数前面，说明传的这个传输为用户名
        return "hello"+username;
    }

结果

Post请求

测试代码

@ApiOperation("post测试类")  //中文注释，放在类上，说明这是h3的控制类类
    @PostMapping("/post")
    public User Post(@ApiParam("用户") User user){  //@ApiParam("用户") 中文注释，放在参数前面，说明传的这个传输为用户名
        return user;
    }

结果