0
点赞
收藏
分享

微信扫一扫

Spring Boot 整合 Swagger

愚鱼看书说故事 2022-04-16 阅读 77
spring boot

Spring Boot 整合 Swagger

Swagger

  • 用于前后端联调,后端自动生成接口文档,前后端可以部署在不同的服务器上,所以为了保证实时性,后端接口一设计就会实时的生成接口文档,前后端相互独立,通过API交互。
  • RestFul Api 文档在线自动生成工具=>Api文档与Api定义同步更新
  • 直接运行,可以在线测试api
  • 支持多种语言
  • 官网:https://swagger.io/
  • 访问:http://localhost:8080/swagger-ui.html

在这里插入图片描述

  • 依赖导入swagger2和swagger-ui
<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
  • swaggerConfig
package com.qiumin.springbootshiro.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
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
@EnableSwagger2
public class swaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qiumin.springbootshiro.controller"))
                .build();
    }


    private ApiInfo getApiInfo(){
        Contact contact = new Contact("邱敏", "https://blog.kuangstudy.com/", "2784618689@qq.com");
        return new ApiInfo("邱敏的SwaggerAPI文档",
                "自律也是一门学问",
                "v1.0",
                "https://blog.kuangstudy.com/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}
  • 配置一个Docket和一个ApiInfo方法用于Docket。
  • 为了解决由于springboot版本过高的问题,需在springboot的配置文件加上spring.mvc.pathmatch.matching-strategy=ant_path_matcher
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

21.1 根据环境判断是否开启swagger

package com.qiumin.springbootshiro.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
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
@EnableSwagger2  //开启swagger2
public class swaggerConfig {

    @Bean
    public Docket docket(Environment environment){
        //根据环境判断是否开启swagger
        Profiles profiles=Profiles.of("dev","test"); //dev test环境下开启
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .enable(flag)  //dev test环境下开启
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qiumin.springbootshiro.controller"))
                .build();
    }


    private ApiInfo getApiInfo(){
        Contact contact = new Contact("邱敏", "https://blog.kuangstudy.com/", "2784618689@qq.com");
        return new ApiInfo("邱敏的SwaggerAPI文档",
                "自律也是一门学问",
                "v1.0",
                "https://blog.kuangstudy.com/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

21.2 分组及接口注释

  • 每一个Docket就是一个组,下面就表示为有三个组,分组可以协作开发,每个人将自己的接口放在自己的组中。
@Bean
public Docket docket2(){  //一组
    return new Docket(DocumentationType.SWAGGER_2).groupName("qiumin1").apiInfo(getApiInfo());
}

@Bean
public Docket docket3(){  //一组
    return new Docket(DocumentationType.SWAGGER_2).groupName("qiumin2").apiInfo(getApiInfo());
}

@Bean
public Docket docket4(){ //一组
    return new Docket(DocumentationType.SWAGGER_2).groupName("qiumin3").apiInfo(getApiInfo());
}
  • 实体类的注解即实体类中字段的解释@ApiModel,@ApiModelProperty,标上了这两个注解在那个swagger页面就会有对应的解释说明
@Data
@AllArgsConstructor
@NoArgsConstructor
//注释
@ApiModel("用户类")
public class userPojo {
    @ApiModelProperty("用户id")
    private Integer id;
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("密码")
    private String password;
    @ApiModelProperty("用户权限")
    private String perms;
}

  • 配置一个访问接口
@RequestMapping("/user")
@ResponseBody
public userPojo getuserPojo(){
    return new userPojo();
}

  • 接口注释 @ApiOperation(“自定义”)
@ApiOperation("登出请求")
@RequestMapping("/loginOut")
private String loginOut(){
    Subject subject = SecurityUtils.getSubject();
    subject.logout();
    return "index";
}

在这里插入图片描述

  • 参数注释 @ApiParam
@RequestMapping("/loginOut")
private String loginOut(@ApiParam("用户名") String username){
    Subject subject = SecurityUtils.getSubject();
    subject.logout();
    return "index";
}

21.3 swagger总结

  1. 可以通过swagger给一些比较难理解的属性或者接口,增加注释信息

  2. 接口文档实时更新

  3. 在swagger页面可以进行测试,通过接口向后端请求数据

  4. 可在线测试 【try it】

  5. 注意点:项目正式发布的时候应将swagger关闭,防止将接口暴露给外界,造成信息安全隐患,而且可以节省运行内存。

    return “index”;
    }


### 21.3 swagger总结

1. 可以通过swagger给一些比较难理解的属性或者接口,增加注释信息
2. 接口文档实时更新
3. 在swagger页面可以进行测试,通过接口向后端请求数据
4. 可在线测试 【try it】
5. **==注意点:项目正式发布的时候应将swagger关闭,防止将接口暴露给外界,造成信息安全隐患,而且可以节省运行内存。==**



**qiumin**
举报

相关推荐

0 条评论