Swagger学习笔记

Swagger学习笔记

看狂神说视频

swagger简介

前后端分离

vue+springboot

后端：后端控制层，服务层，数据访问层

前端：前端控制层，视图层

• 伪造后端数据json，已经存在了，没有后端，前端工程依旧可以跑起来
• 前后端如何交互===>API
• 前后端相对独立，松耦合
• 前后端甚至可以部署在不同的服务器上；

产生的问题是：

• 前后端集成联调，前端人员和后端人员无法做到“即使协商，尽早解决”最终导致问题集中爆发

解决方案：

• 首先指定schema[计划的提纲]。实时更新最新API，降低集成的风险；

• 早些年：指定word计划文档

• 前后端分离：

  前端测试后端接口：postman

  后端提供接口，需要实时更新最新的消息及改动

**Swagger **特点

• 号称世界最流行的API框架；

• RestFul Api 文档在线自动生成工具=>Api文档与API定义同步更新

• 直接运行，可以在线测试API接口

• 支持多种语言

官网：https://swagger.io/

Swagger在项目中使用

需要springbox

• swagger2

• ui

springboot集成swagger

1.新建springboot -web项目

2.导入依赖

<dependencies>
 
    <!-- 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>
</dependencies>

3.编写一个hello工程

package com.example.swaggerdemo.controller;


import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SwaggerController {

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

4.配置swagger==>config

package com.example.swaggerdemo.config;

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

@Configuration//将配置配置到springboot
@EnableSwagger2//开启swagger2
public class SwaggerConfig {
}

5.测试运行

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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-0aN6GrRK-1632899185619)(C:\Users\应孑\AppData\Roaming\Typora\typora-user-images\image-20210929104302629.png)]

6.配置swagger

swagger的bean实例

package com.example.swaggerdemo.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;

@Configuration//将配置配置到springboot
@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://blog.csdn.net/qq_44647596?spm=1001.2101.3001.5343","1324232975@qq.com");
        return new ApiInfo(
                "应孑的swaggerAPI文档", //文档标题
                "Api Documentation", //文档描述
                "1.0", //版本号
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList ());

    }
}

7.swagger配置扫描接口

                .select ()
                //RequestHandlerSelectors,配置要扫描的接口的方式
                //basePackage：指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation:扫描类上的注解
                //withMethodAnnotation:扫描方法上的注解
                //一般用的basePackage
                .apis ( RequestHandlerSelectors.basePackage ( "com.example.swaggerdemo.controller" ) )
                //过滤什么路径,将swaggerdemo下的路径都过滤掉了，swagger上不显示
                .paths ( PathSelectors.ant (  "/swaggerdemo/**") )
                .build ();//

关闭

 //enable是否启用swagger，if为false，则swagger不能在浏览器中访问
                .enable ( false )

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Xey0Uspi-1632899185625)(C:\Users\应孑\AppData\Roaming\Typora\typora-user-images\image-20210929112007897.png)]

实例题：

我希望我的swagger只在生产环境中使用，在发布的时候不使用，如何解决

思路：

• 获取环境，
• 判断是否是生产环境
• 注入enable

设置配置环境

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-YbujjVuP-1632899185630)(C:\Users\应孑\AppData\Roaming\Typora\typora-user-images\image-20210929140559489.png)]

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-WWU6KQei-1632899185640)(C:\Users\应孑\AppData\Roaming\Typora\typora-user-images\image-20210929140621501.png)]

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-dMnElIrD-1632899185644)(C:\Users\应孑\AppData\Roaming\Typora\typora-user-images\image-20210929140644735.png)]

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-csfLtpuz-1632899185651)(C:\Users\应孑\AppData\Roaming\Typora\typora-user-images\image-20210929140659668.png)]

    //设置要显示的swagger环境
        Profiles profiles= Profiles.of ("dev");//可以配置多个，只显示了dev，过滤掉了其他环境
        //通过environment.acceptsProfiles 判断是否处在自己设定的环境中获取项目的环境
       boolean flag=environment.acceptsProfiles (  profiles);
        return new Docket ( DocumentationType.SWAGGER_2 )
                .apiInfo ( apiInfo () )
                //enable是否启用swagger，if为false，则swagger不能在浏览器中访问
                .enable ( flag )

8.配置API文档的分组

 return new Docket ( DocumentationType.SWAGGER_2 )
                .apiInfo ( apiInfo () )
               //配置分组
                .groupName ( "zhongyan" )

实例：如何配置多个分组,可以实现多人协作，管理不同的接口

    @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" );

    }

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-ko5X73dK-1632899185656)(C:\Users\应孑\AppData\Roaming\Typora\typora-user-images\image-20210929142306171.png)]

//Controller.java

//只要我们的接口中，返回值中存在实体类，它就会被扫描到swagger中
    @ApiOperation ( "方法注释" )
    @PostMapping(value = "/user")
    public User user(){
        return  new User ();
    }
    @ApiOperation ( "方法注释" )
    @PostMapping(value = "/user")
    public String hello2(@ApiParam("参数注释")String username){
        return  username;
    }

实体类User.java

package com.example.swaggerdemo.pojo;

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

//ApiModel作用是给实体类注释在swagger中
@ApiModel("用户实体类")
public class User {
    //ApiModelProperty作用是给字段注释
    @ApiModelProperty("用户名")
    public String userName;
    @ApiModelProperty("密码")
    public String password;

}

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-EFCRrqG5-1632899185658)(C:\Users\应孑\AppData\Roaming\Typora\typora-user-images\image-20210929143407000.png)]

总结：

• 可以通过swagger给一些比较难理解的属性或者接口增加注释
• 接口文档实时更新
• 可以在线测试
• 在正式发布的时候，关闭Swagger，出于考虑安全防止用户得到接口信息，且可以节省运行内存