功能如此强大的 Swagger !

程序员考拉

共 3768字,需浏览 8分钟

 ·

2020-12-26 23:31

公众号关注 “GitHub今日热榜
设为 “星标”,带你挖掘更多开发神器!




前言


Swagger 是什么?


Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。


1.作用:


  1. 启动项目后在线自动生成API文档

  2. 在线高效调试


2.官网:https://swagger.ioknife4j 是什么?


  • 为Java MVC框架集成Swagger的增强解决方案-前身是 swagger-bootstrap-ui

  • swagger-bootstrap-ui是springfox-swagger的增强UI实现,为Java开发者在使用Swagger的时候,能拥有一份简洁、强大的接口文档体验


1.作用:


  1. 接口排序

  2. 自定义文档说明

  3. 访问权限控制

  4. 请求参数缓存

  5. 调试动态请求参数

  6. 文档说明等


2.官网:https://doc.xiaominfo.com


整合一、pom.xml 引入 依赖


    <dependency>
      <groupId>io.springfoxgroupId>
      <artifactId>springfox-swagger2artifactId>
      <version>2.9.2version>
      <exclusions>
          <exclusion>
              <groupId>io.swaggergroupId>
              <artifactId>swagger-annotationsartifactId>
          exclusion>
          <exclusion>
              <groupId>io.swaggergroupId>
              <artifactId>swagger-modelsartifactId>
          exclusion>
      exclusions>
    dependency>
    
    
        <dependency>
            <groupId>io.swaggergroupId>
            <artifactId>swagger-annotationsartifactId>
            <version>1.5.21version>
        dependency>
        
        <dependency>
            <groupId>io.swaggergroupId>
            <artifactId>swagger-modelsartifactId>
            <version>1.5.21version>
        dependency>

    
    <dependency>
      <groupId>io.springfoxgroupId>
      <artifactId>springfox-swagger-uiartifactId>
      <version>2.9.2version>
    dependency>
    <dependency>
      <groupId>com.github.xiaoymingroupId>
      <artifactId>knife4j-spring-boot-starterartifactId>
      <version>2.0.2version>
    dependency>


二、创建swagger配置文件(swaggerConfig.java)


@Configuration // 声明为配置文件,让spring加载
@EnableSwagger2 // 支持swagger2插件配置
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {

  // apiInfo对象主要是设置我们api文档的标题,描述,访问的地址,创建者等信息
  @SuppressWarnings("deprecation")
  @Bean
  public ApiInfo apiInfo()
{
    return new ApiInfoBuilder()
        .title("浓密秀发之谦先生的Api接口文档")
        .description("快速进行Api接口调试")
        .termsOfServiceUrl("127.0.0.1:8080")
        .contact("Qian")
        .version("1.0")
        .build();
  }

  /**
   * 创建API
   */

  @Bean
  public Docket createRestApi()
{
    return new Docket(DocumentationType.SWAGGER_2)
        // .pathMapping("/dev-api")
        // 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
        .apiInfo(apiInfo())
        // 设置哪些接口暴露给Swagger展示
        .select()
        // 扫描所有有注解的api,用这种方式更灵活
        // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        // 扫描指定包中的swagger注解
        .apis(RequestHandlerSelectors.basePackage("cn.timer.api"))
        // 扫描所有 .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any()).build()
        /* 设置安全模式,swagger可以设置访问token */
        .securitySchemes(securitySchemes()).securityContexts(securityContexts());
  }

  /**
   * 安全模式,这里指定token通过Authorization头请求头传递
   */

  private List securitySchemes() {
    List apiKeyList = new ArrayList();
    apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
    return apiKeyList;
  }

  /**
   * 安全上下文
   */

  private List securityContexts() {
    List securityContexts = new ArrayList<>();
    securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth())
        .forPaths(PathSelectors.regex("^(?!auth).*$")).build());
    return securityContexts;
  }

  /**
   * 默认的安全上引用
   */

  private List defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    List securityReferences = new ArrayList<>();
    securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
    return securityReferences;
  }

}


三、启动项目,访问 http://localhost:8089/doc.html (请求的端口看自身情况,我项目配置的是8089)


补充:API排序需要开启 增强模式


若无法访问或访问后API无法正常显示,原因有以下几点:


  1. 路径 http://localhost:8089/doc.html 被拦截

  2. 静态资源被后端拦截,如 js、html等


效果图





注解


  • tag排序:
    @Api(tags = "1.0登录")
    @Api(tags = "2.0注册")

  • api排序:
    @ApiOperationSupport(order = 1)
    @ApiOperationSupport(order = 2)


整合过程中遇到的问题:


  • @ApiModelProperty注解example属性格式无法被解析
    @ApiModelProperty(value = "是否默认", example = "["0","1"]")
    example 的值 [“0”,“1”] 数组格式无法被解析,建议该为{}或字符串



原文链接:blog.csdn.net/weixin_38150130/article/details/105650695








关注GitHub今日热榜,专注挖掘好用的开发工具,致力于分享优质高效的工具、资源、插件等,助力开发者成长!







点个在看 你最好看










浏览 49
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报
评论
图片
表情
推荐
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报