Swagger3 + 离线文档笔记

本文章仅作为个人笔记

官方网站 / 参考文档 / 官方项目 / 个人 demo

wagger 的集成与静态文件生成 (在线/离线文档)

新建springboot项目并在build.gradle文件添加相关依赖

  # 引用插件(不生成离线文档可以不引入)
  plugins {
      id 'org.asciidoctor.convert' version '2.3.0'
      id "io.github.lhotari.swagger2markup" version "1.3.3.1"
  }
  # 解决中文乱码问题
  tasks.withType(JavaCompile) {
      options.deprecation = true
      options.encoding = 'UTF-8'
      options.compilerArgs << "-Xlint:unchecked"
  }
  # 设置仓库
  repositories {
      jcenter()
      mavenCentral()
  }
  # 设置输出文件夹及swagger版本
  ext {
      swaggerVersion = "3.0.0"
      swaggerOutputDir = file("${project.rootDir}/api/swagger")
      asciiDocOutputDir = file("${project.rootDir}/api/asciidoc")
      snippetsOutputDir = file("${project.rootDir}/api/snippets")
  }
  # 引用依赖
  dependencies {
      // swagger3 依赖
      implementation("io.springfox:springfox-boot-starter:${swaggerVersion}")
      // 离线文档生成 依赖(不生成离线文档可以不引入)
      implementation("io.github.swagger2markup:swagger2markup:1.3.3")
      // 测试 依赖(不生成离线文档可以不引入)
      testImplementation("org.springframework.boot:spring-boot-starter-test")
      testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc")
  }
  # 设置全局离线文档输出地址 (不生成离线文档可以不设置)
  test {
      systemProperty 'io.springfox.staticdocs.outputDir', swaggerOutputDir
      systemProperty 'io.springfox.staticdocs.snippetsOutputDir', snippetsOutputDir
      # 构建时忽略 生成文件的测试
      exclude '**/DemoApplicationTests.class'
  }
  # 添加离线文档转换task (不生成离线文档可以不设置)
  convertSwagger2markup {
      dependsOn test
      swaggerInput "${swaggerOutputDir}/swagger.json"
      outputDir asciiDocOutputDir
      config = [
              'swagger2markup.pathsGroupedBy'                          : 'TAGS',
              'swagger2markup.extensions.springRestDocs.snippetBaseUri': snippetsOutputDir.getAbsolutePath()]
  }
  # 添加离线文档生成task (不生成离线文档可以不设置)
  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
  }

为项目添加 swagger 配置开启swagger/设置swagger基本信息等

  # 自定义swagger开关 在 application.yml 添加对应配置打开或者不设置便关闭
  @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("图模服务")
              .version("1.0")
              .build();
  }

为项目添加单元测试，用于生成静态 adoc/md/json 文件(不生成静态文件请忽略)

  # 获取设置的静态文件生成路径
  String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
  # 根据api获取接口内容
  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"));

做好准备工作为相应的接口(api/controller)添加对应swagger注解具体用法自行参考官方文档

最后运行

  gradle build test
  gradle build asciidoctor

至此便完成了 swagger3 的集成与静态文件的生成
最后奉上个人demo用于参考

Swagger3 + 离线文档 笔记

本文章仅作为个人笔记

官方网站 / 参考文档 / 官方项目 / 个人 demo

Swagger3 + 离线文档笔记