Swagger Api工具

Posted 2021-07-20 暴躁的程序猿啊

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Swagger Api工具相关的知识，希望对你有一定的参考价值。

Swagger简介

Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.

前后端分离时代
后端：后端控制层，服务层，数据访问层[后端团队]
前端：前端控制层，视图层[前端团队]
伪造后端数据，json。已经存在了不需要后端，前端工程依旧能跑起来了

前后端如何交互==>API接口
前后端相互独立，松耦合。
前后端甚至可以部署在不同的服务器上

产生一个问题：
前后端集成联调，前端人员和后端人员无法做到及时协商，尽早解决。
解决方案：
首先制定一个计划提纲，实时更新API，降低集成风险;
早些年:制定word文档
前后端分离:
Swagger:
号称世界上最流行的API框架;
RestFul Api 文档在线自动生成工具=>Api文档与Api定义同步更新
直接运行可以在线测试API接口
支持多种语言：java php。。
官网：
https://swagger.io/
在项目中使用swagger
需要Springbox
两个jar包
1.swagger2
2.ui
在这里插入图片描述

Springboot集成swagger
1.新建一个springboot-web项目
2.导入相关依赖

  <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- 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>

3.编写一个hello工程

	@RestController
	public class HelloController {


 @RequestMapping(value = "/hello")
	    public String hello(){
	       return "hello";
	    }

}

4.配置swagger ==>配一个config

   @Configuration//写了之后会被扫描进去
@EnableSwagger2//  开启swagger2
public class SwaggerConfig {

}

重启测试可以使用了最基础的使用
访问这个地址就可以访问swagger的页面
http://localhost:8080/swagger-ui.html
在这里插入图片描述

配置Swagger

Swagger的bean实例Docket;

@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.baidu.com","12352352@qq.com");
        return  new ApiInfo(
              "程序猿的第一个Swagger API文档",
              "学无止境！！！",
              "1.0",
              "https://www.baidu.com", contact,
              "Apache 2.0",
              "http://www.apache.org/licenses/LICENSE-2.0",
              new ArrayList());

    }

}

Swagger配置扫描接口
Docket.select()

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors配置要扫描接口的方式
            //.basePackage()基于哪个包去扫描
            //any():扫描全部
            //none:不扫描
            //withClassAnnotation :扫描类上的注解,参数是一个注解的反射对象
            //withMethodAnnotation :扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.rpf.swagger.controller"))
            //过滤path() 过滤什么路径
            //ant指定路径   只扫描rpf下的
            .paths(PathSelectors.ant("/rpf/**"))
            .build()  //工厂模式
     ;
}

配置是否启动Swagger

我只希望我的swagger在生产环境中使用，在发布的时候不使用
思路：判断是否是生产环境 flag = false
注入enable()

	 @Configuration//写了之后会被扫描进去
@EnableSwagger2//  开启swagger2
public class SwaggerConfig {

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的swagger环境   生产环境下使用swagger
        Profiles profiles= Profiles.of("dev","test");
        //获取项目的环境environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean b = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)//是否启动swagger  如果为false则swagger不能在浏览器中访问
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                //.basePackage()基于哪个包去扫描
                //any():扫描全部
                //none:不扫描
                //withClassAnnotation :扫描类上的注解,参数是一个注解的反射对象
                //withMethodAnnotation :扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.rpf.swagger.controller"))
                //过滤path() 过滤什么路径
                //ant指定路径   只扫描rpf下的
//                .paths(PathSelectors.ant("/rpf/**"))
                .build()  //工厂模式
         ;
    }

判断如果当前不是生产环境无法访问页面是生产环境时才能访问

porperties文件写法
在这里插入图片描述

发布端口号

在这里插入图片描述
现在指定了生产环境只有访问8081端口才能进去

设置分组

.groupName(“程序猿”)//配置分组

//配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的swagger环境   生产环境下使用swagger
        Profiles profiles= Profiles.of("dev","test");
        //获取项目的环境environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean b = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)//是否启动swagger  如果为false则swagger不能在浏览器中访问
                .groupName("程序猿")//配置分组
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rpf.swagger.controller"))
//                .paths(PathSelectors.ant("/rpf/**"))
                .build()  //工厂模式
         ;
    }

如何设置多个分组
配置多个Docket

    @Bean
    public Docket dcoket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
  @Bean
    public Docket dcoket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
  @Bean
    public Docket dcoket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

当我们添加一个pojo类时怎么才能被扫描进去呢
pojo类

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

我们需要新建一个controller接口把这个类返回就可以被自动扫描进去了

 //只要我们的接口中，返回值中存在实体类，他就会被扫描到swagger中
    @PostMapping(value = "/user")
    public User user(){
       return new User();
    }

在这里插入图片描述
那么怎么在字段等地方加上如上图的注释呢？
使用@Api…注解
写在pojo类上

//@Api(注释)
@ApiModel("用户实体类")//文档注释
public class User {
    @ApiModelProperty("用户名")//给字段加注释
    public String username;
    @ApiModelProperty("密码")//给字段加注释
    public String password;
}

效果
在这里插入图片描述
给方法@ApiOperation和参数@ApiParam写配置

 @ApiOperation("hello 控制类")//给方法加注释
    @GetMapping(value = "/user")//@ApiParam给方法参数加注释
    public String hello2(@ApiParam("用户名") String username){
        return username;
    }

在这里插入图片描述
重要的一个功能在线测试接口

完成之后响应的返回值

swagger的最终配置
swaggerconfig

@Configuration//写了之后会被扫描进去
@EnableSwagger2//  开启swagger2
public class SwaggerConfig {

    @Bean
    public Docket dcoket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
  @Bean
    public Docket dcoket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
  @Bean
    public Docket dcoket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的swagger环境   生产环境下使用swagger
        Profiles profiles= Profiles.of("dev","test");
        //获取项目的环境environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean b = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)//是否启动swagger  如果为false则swagger不能在浏览器中访问
                .groupName("程序猿")//配置分组
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                //.basePackage()基于哪个包去扫描
                //any():扫描全部
                //none:不扫描
                //withClassAnnotation :扫描类上的注解,参数是一个注解的反射对象
                //withMethodAnnotation :扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.rpf.swagger.controller"))
                //过滤path() 过滤什么路径
                //ant指定路径   只扫描rpf下的
//                .paths(PathSelectors.ant("/rpf/**"))
                .build()  //工厂模式
         ;
    }
    //配置Swagger文档的信息apiInfo
    private ApiInfo  apiInfo(){
        //作者信息
        Contact contact = new Contact("程序猿","https://www.baiduuu.com","12352352@qq.com");
        return  new ApiInfo(
              "程序猿的第一个Swagger API文档",
              "学无止境！！！",
              "1.0",
              "https://www.baiduuu.com", contact,
              "Apache 2.0",
              "http://www.apache.org/licenses/LICENSE-2.0",
              new ArrayList());

    }

}

controller

@RestController
public class HelloController {


    @GetMapping(value = "/hello")
    public String hello(){
       return "hello";
    }
    //只要我们的接口中，返回值中存在实体类，他就会被扫描到swagger中
    @PostMapping(value = "/user")
    public User user(){
       return new User();
    }

    @ApiOperation("hello 控制类")//给方法加注释
    @GetMapping(value = "/user")//@ApiParam给方法参数加注释
    public String hello2(@ApiParam("用户名") String username){
        return username;
    }

}

总结：
优点：
我们可以通过swagger给一写比较难理解的属性或接口增加注释信息
可以在线测试
接口文档实时更新
注:正式上线的版本关闭swagger

以上是关于Swagger Api工具的主要内容，如果未能解决你的问题，请参考以下文章

springboot2.0入门--swagger2接口API构建

1 API接口文档规范Swagger3 简介

Django Rest Swagger生成api文档

spring boot2集成api文档工具swagger-ui(下)

Django Rest framework Swagger生成api文档