• Swagger介绍


    导语

    相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。

    Swagger是什么?它能干什么?

    发现了痛点就要去找解决方案。解决方案用的人多了,就成了标准的规范,这就是Swagger的由来。通过这套规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
    但即便如此,对于许多开发来说,编写这个yml或json格式的描述文件,本身也是有一定负担的工作,特别是在后面持续迭代开发的时候,往往会忽略更新这个描述文件,直接更改代码。久而久之,这个描述文件也和实际项目渐行渐远,基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。

    介绍

    Swagger是一个接口文档生成工具,同时提供接口测试调用的辅助功能。

    关于 Swagger

    Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因:
    mSwagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。
    Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
    Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
    Swagger 有一个强大的社区,里面有许多强悍的贡献者。
    Swagger 文档提供了一个方法,使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API,包括了比如 names、order 等 API 信息。
    你可以通过一个文本编辑器来编辑 Swagger 文件,或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。
    注意:用 Swagger 文件生成互动的 API 文档是最精简的,它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。

    swagger调式技巧

    • 本文主要介绍本项目采用Swagger方式
      • 通过网关访问Swagger,该Swagger会把聚合后的文档进行访问需要配置哪些参数
      • 访问单个服务时,需要配置哪些参数
      • 枚举如何传递参数(@RequestParam @RequestBody)
      • LocalDateTime、LocalDate、LocalTime、 Date类型如何传递(@RequestParam @RequestBody)

    以下是采用knife4j2.0.8版本进行封装成start,通过yml文件配置,自动创建docket案例,省去了每次项目引用都要去创建config类并去手动创建docket

    • knife4j-sjk-springboot-autoconfiguration和nife4j-sjk-springboot-start
      已经封装成star进行自动装配,通过在yml配置,自动创建docket和分组docket;yml配置如下
    # knife4j 全局配置, 参考knife4j官方文档
       knife4j:
         enable: true
         setting:
           enableReloadCacheParameter: true
           enableVersion: true
           enableDynamicParameter: true
           enableFooter: false
           enableFooterCustom: true
           footerCustomContent: Apache License 2.0 | Copyright 2020 [百度](http://baidu.com)
    
    • knife4j 提供了生产环境禁用、访问密码、修改文档基础样式等功能, 更多功能参考: knife4j
    • SwaggerProperties 提供了动态配置docket文档的能力, 修改 lamp-xxx-server.yml 配置文件配置多个文档group.
    sjk:
      swagger:
        docket:
          auth:
            title: xxx模块接口
            base-package: com.knife4j.sjk.demo.controller
          common:
            title: 公共模块
            base-package: com.knife4j.sjk.demo.controller
    

    knife4j-sjk-start-demo是引用start一个demo例子,具体demo源码详细地址见
    github demo源码

    参考地址:
    https://www.cnblogs.com/shihaiming/p/12343314.html
    https://gitee.com/xiaoym/knife4j

    开源仓库

    Github
    https://github.com/xiaoymin/swagger-bootstrap-ui
    码云
    https://gitee.com/xiaoym/knife4j

    Demo
    https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

  • 相关阅读:
    Unity的动态加载简单使用
    枚举的使用总结
    IIS WEB程序如何访问共享目录
    AngularJS之页面跳转Route
    ASP.NET MVC4 BundleConfig的注意事项
    Android自动化测试------monkey自定义脚本(四)
    Android自动化测试------monkey(三)
    Android自动化测试------monkey(二)
    Android自动化测试------monkey(一)
    (一)adb命令的使用
  • 原文地址:https://www.cnblogs.com/sjkzy/p/14309739.html
Copyright © 2020-2023  润新知