介绍

  • 开发中的接口文档很重要
  • 我最开始时使用postman手写，后面用了apidoc，最后才用的swagger
  • 说说swagger吧
    • 功能很强大
    • 自带的参数判空验证很鸡肋
      • 脱离了swagger的前端页面就完全失去了作用
    • 对代码的入侵特别大
      • 到处都是他的注解
      • 还有很多配置文件
    • 为什么还要用呢
      • 他们都用为了统一
        • 我又开始是拒绝的，其实apidoc很不错的
      • 自动化程度高
        • 建立在注解的基础上的
      • 文档清晰
        • 建立在更换了UI界面基础上的
        • 原生的像屎
  • 此模块满足了以下功能
    • 将一些配置提取到了配置文件
      • 虽然现在新的版本好像自己就做了，但是我弄的时候没有
    • 使用了开源UI界面把原生的替换掉了

引入依赖

单机跟cloud的唯一区别就是 cloud可以使用 nacos聚合文档

springboot 单机版

已测试

  • 单机版没有依赖cloud相关的组件

    1. <dependency>
    2.           <groupId>org.springframework.boot</groupId>
    3.           <artifactId>spring-boot-starter-web</artifactId>
    4.       </dependency>
    5.       <dependency>
    6.     <!-- springboot 单机版 -->
    7.           <groupId>com.detabes</groupId>
    8.           <artifactId>doc-swagger-boot</artifactId>
    9.           <version>1.0.0</version>
    10.       </dependency>
    11.       <dependency>
    12.           <groupId>org.springframework.boot</groupId>
    13.           <artifactId>spring-boot-starter-test</artifactId>
    14.           <scope>test</scope>
    15.       </dependency>

    springcloud版

    暂时未测试

  • 使用了nacos注册中心

    1.      <!-- springcloud  doc 版 -->
    2.       <dependency>
    3.           <groupId>com.detabes</groupId>
    4.           <artifactId>doc-swagger-cloud</artifactId>
    5.           <version>1.0.0</version>
    6.       </dependency>
    7.    <!-- springcloud版 -->
    8.       <dependency>
    9.           <groupId>org.springframework.boot</groupId>
    10.           <artifactId>spring-boot-starter-test</artifactId>
    11.           <scope>test</scope>
    12.       </dependency>
    13.   <dependency>
    14.     <groupId>org.springframework.boot</groupId>
    15.     <artifactId>spring-boot-starter-web</artifactId>
    16.   </dependency>
    17.       <!-- nacos -->
    18.       <dependency>
    19.           <groupId>com.alibaba.cloud</groupId>
    20.           <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    21.           <version>2.2.3.RELEASE</version>
    22.       </dependency>
    23.       <dependency>
    24.           <groupId>com.alibaba.cloud</groupId>
    25.           <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    26.           <version>2.2.3.RELEASE</version>
    27.       </dependency>
    28.       <!-- nacos-config -->
    29.       <dependency>
    30.           <groupId>com.alibaba.boot</groupId>
    31.           <artifactId>nacos-config-spring-boot-starter</artifactId>
    32.           <version>0.2.7</version>
    33.       </dependency>

    开始配置

  • 配置下包扫描就行了（默认扫描的是 com.detabes.controller ）

  • 其他的配置看注释把

    springboot 单机版

    1. detabes.swagger.base-package=com.example.doc.swager.boot.controller

    springcloud版

  • bootstrap.yml ```yaml server: port: 1241 spring: main: allow-bean-definition-overriding: true profiles: active: def application: name: cloud-demo detabes: swagger: base-package=com:

    1. example:
    2.   doc:
    3.     swager:
    4.       boot:
    5.         controller: com.example.doc.swagger.cloud.controller

logging: config: classpath:logback-spring.xml debug: false

  2. - bootstrap-def.yml
  3. ```yaml
  4. spring:
  5.   cloud:
  6.     nacos:
  7.       discovery:
  8.         server-addr: 127.0.0.1:8848 # 注册中心
  9.       config:
  10.         server-addr: 127.0.0.1:8848 # 配置中心
  11.         file-extension: yaml  #文件扩展名格式,针对于默认的{spring.application.name}-${profile}.${file-extension:properties}配置
  12.         enabled: true #开启或关闭配置中心
  13.         encode: UTF-8

示例测试

  • 接口示例 (boot - cloud) ```java

import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController;

/**

  • @author tn
  • @version 1
  • @ClassName SwaggerController
  • @description 测试swaggger接口文档

  • @date 2020/12/22 15:12 */ @RestController @RequestMapping(“swagger”) @Api(tags = “测试swaggger接口文档”) public class SwaggerController {

    @GetMapping(“/getMethod”) @ApiOperation(value = “测试接口1”, notes = “测试swaggger接口文档”) public String getMethod() {

    1.  return "hi swagger";

    }

    @GetMapping(“/getMethodTwo”) @ApiOperation(value = “测试接口2”, notes = “测试swaggger接口文档”) @ApiImplicitParam(value = “姓名”, name = “name”, dataTypeClass = String.class) public String getMethodTwo(String name) {

    1.  return "hi swagger:"+name;

    } }

```