Swagger的学习

Posted 2021-05-16 我是一个邓疯子

Swagger

• 号称世界上最流行的Api框架;
• RestFul Api文档在线自动生成工具=>Api文档与API定义同步更新
• 直接运行,可以在线测试API接口
• 支持多种语言:(Java,php...)

Swagger官网

在项目中使用Swagger需要springbox:

• swagger2
• ui

SpringBoot集成Swagger

1.新建一个SpringBoot-web项目

2.导入相关依赖(关于Swagger新版本（3.0.0)打不开swagger-ui.html:经过半天的排坑才发现，原来在swagger-ui3.0.0的jar包目录下找不到swagger-ui.html这个页面应该有其它的解决办法，我的解决办法就是把swagger的版本降低，降低到jar包配置路径下有swagger-ui.html的就行了，并不是我们配置的问题,降级直接换成2.9.2就可以进入)

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

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

3.编写一个hello工程

4.配置Swagger=>config

package cn.dzp.swagger.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

5.测试运行

配置Swagger

Swagger的bean实例Docket

package cn.dzp.swagger.config;

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

import java.util.ArrayList;

import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了Swagger的Docket的bean
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
//    配置Swagger信息apiInfo
    private ApiInfo apiInfo(){
//        作者信息
        Contact contact = new Contact("邓疯子", "https://www.cnblogs.com/feng-zhi/", "[e-mail]");
        return new ApiInfo(
                "邓疯子的SwaggerAPI文档",
                "学到老活到老",
                "v1.0",
                "https://www.cnblogs.com/feng-zhi/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

重启项目测试

Swagger配置扫描接口

Docket.select()

当过滤也开启时,不能扫到任何接口

关闭过滤了,我只选择了basePackage("cn.dzp.swagger.controller"),所以只能扫到我的HelloController

是否开启swagger enable(false),fasle表示不启动,默认true启动

编写工作环境,在判断环境选择是否开启swagger

当默认环境8080,失败

切换到dev环境8081查看项目成功

配置API文档的分组(groupName())

一个分组对应一个Docket的实例,多个分组需要实现多个实例(新建了三个分组实例)
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("黄小姐");
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("邓学长");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("Godas_lsy");
}

启动项目检查

实体类配置

编写实体类
package cn.dzp.swagger.pojo;

public class User {
    public String username;
    public String password;
}

控制层

//    只要接口中返回值存在实体类,他就会被扫描
    @PostMapping("/user")
    public User user(){
        return new User();
    }
}

开启项目

可以添加中文注释对于一些较难理解的类和属性

//    ApiOperation接口不是放在类上的,是方法上
    @ApiOperation("hello控制类")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }

总结Swagger;

1.我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息
2.接口文档实时更新
3.可以在线测试

Swagger是个优秀的工具,几乎所有大公司都有使用它

注意点:在正式发布的时候,关闭Swagger!!!出于安全考虑,而且节省运行的内存.