本文章僅作為個(gè)人筆記

官方網(wǎng)站 / 參考文檔 / 官方項(xiàng)目 / 個(gè)人 demo

• wagger 的集成與靜態(tài)文件生成 (在線(xiàn)/離線(xiàn)文檔)

  • 新建springboot項(xiàng)目并在build.gradle文件添加相關(guān)依賴(lài)

      # 引用插件(不生成離線(xiàn)文檔可以不引入)
      plugins {
          id 'org.asciidoctor.convert' version '2.3.0'
          id "io.github.lhotari.swagger2markup" version "1.3.3.1"
      }
      # 解決中文亂碼問(wèn)題
      tasks.withType(JavaCompile) {
          options.deprecation = true
          options.encoding = 'UTF-8'
          options.compilerArgs << "-Xlint:unchecked"
      }
      # 設(shè)置倉(cāng)庫(kù)
      repositories {
          jcenter()
          mavenCentral()
      }
      # 設(shè)置輸出文件夾及swagger版本
      ext {
          swaggerVersion = "3.0.0"
          swaggerOutputDir = file("${project.rootDir}/api/swagger")
          asciiDocOutputDir = file("${project.rootDir}/api/asciidoc")
          snippetsOutputDir = file("${project.rootDir}/api/snippets")
      }
      # 引用依賴(lài)
      dependencies {
          // swagger3 依賴(lài)
          implementation("io.springfox:springfox-boot-starter:${swaggerVersion}")
          // 離線(xiàn)文檔生成 依賴(lài)(不生成離線(xiàn)文檔可以不引入)
          implementation("io.github.swagger2markup:swagger2markup:1.3.3")
          // 測(cè)試 依賴(lài)(不生成離線(xiàn)文檔可以不引入)
          testImplementation("org.springframework.boot:spring-boot-starter-test")
          testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc")
      }
      # 設(shè)置全局離線(xiàn)文檔輸出地址 (不生成離線(xiàn)文檔可以不設(shè)置)
      test {
          systemProperty 'io.springfox.staticdocs.outputDir', swaggerOutputDir
          systemProperty 'io.springfox.staticdocs.snippetsOutputDir', snippetsOutputDir
          # 構(gòu)建時(shí)忽略 生成文件的測(cè)試
          exclude '**/DemoApplicationTests.class'
      }
      # 添加離線(xiàn)文檔轉(zhuǎn)換task (不生成離線(xiàn)文檔可以不設(shè)置)
      convertSwagger2markup {
          dependsOn test
          swaggerInput "${swaggerOutputDir}/swagger.json"
          outputDir asciiDocOutputDir
          config = [
                  'swagger2markup.pathsGroupedBy'                          : 'TAGS',
                  'swagger2markup.extensions.springRestDocs.snippetBaseUri': snippetsOutputDir.getAbsolutePath()]
      }
      # 添加離線(xiàn)文檔生成task (不生成離線(xiàn)文檔可以不設(shè)置)
      asciidoctor {
          dependsOn convertSwagger2markup
          sourceDir = file("${swaggerOutputDir}")
          sources {
              include 'index.adoc'
          }
          backends = ['html5']
          attributes = [
                  doctype    : 'book',
                  toc        : 'left',
                  toclevels  : '3',
                  numbered   : '',
                  sectlinks  : '',
                  sectanchors: '',
                  hardbreaks : '',
                  generated  : swaggerOutputDir
          ]
          outputDir = swaggerOutputDir
      }
    

  • 為項(xiàng)目添加 swagger 配置 開(kāi)啟swagger/設(shè)置swagger基本信息等

      # 自定義swagger開(kāi)關(guān) 在 application.yml 添加對(duì)應(yīng)配置打開(kāi)或者不設(shè)置便關(guān)閉
      @Value("${swagger.enable:false}")
      private boolean swaggerEnable;
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.OAS_30)
                  .enable(swaggerEnable)
                  .apiInfo(apiInfo())
                  .select()
                  .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                  .paths(PathSelectors.any())
                  .build();
      }
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title("圖模服務(wù)")
                  .version("1.0")
                  .build();
      }
    

  • 為項(xiàng)目添加單元測(cè)試，用于生成靜態(tài) adoc/md/json 文件(不生成靜態(tài)文件請(qǐng)忽略)

      # 獲取設(shè)置的靜態(tài)文件生成路徑
      String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
      # 根據(jù)api獲取接口內(nèi)容
      MvcResult mvcResult = this.mockMvc
              .perform(get("/v2/api-docs")
                      .accept(MediaType.APPLICATION_JSON))
              .andExpect(status().isOk())
              .andReturn();
      MockHttpServletResponse response = mvcResult.getResponse();
      response.setCharacterEncoding("utf-8");
      String swaggerJson = response.getContentAsString();
      Files.createDirectories(Paths.get(outputDir));
      # 輸出為 json 文件
      try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir,
              "swagger.json"), StandardCharsets.UTF_8)) {
          writer.write(swaggerJson);
      }
      Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
              .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
              .withOutputLanguage(Language.ZH)
              .withPathsGroupedBy(GroupBy.TAGS)
              .withGeneratedExamples()
              .withoutInlineSchema()
              .build();
      # 輸出為 asciidoc 文件
      Swagger2MarkupConverter.from(swaggerJson)
              .withConfig(config)
              .build()
              .toFile(Paths.get(outputDir + "/index"));
      config = new Swagger2MarkupConfigBuilder()
              .withMarkupLanguage(MarkupLanguage.MARKDOWN)
              .withOutputLanguage(Language.ZH)
              .withPathsGroupedBy(GroupBy.TAGS)
              .withGeneratedExamples()
              .withoutInlineSchema()
              .build();
      # 輸出為 md 文件
      Swagger2MarkupConverter.from(swaggerJson)
              .withConfig(config)
              .build()
              .toFile(Paths.get(outputDir + "/index"));
    

  • 做好準(zhǔn)備工作為相應(yīng)的接口(api/controller)添加對(duì)應(yīng)swagger注解 具體用法自行參考官方文檔

  • 最后運(yùn)行

      gradle build test
      gradle build asciidoctor
    

  • 至此便完成了 swagger3 的集成與靜態(tài)文件的生成

  • 最后奉上個(gè)人demo用于參考