SpringBoot工程后端文档生成姿势

admin 109 0

整体步骤

  • Swagger 和 Knife4j 是老生常谈了。

  • 整合Swagger,生成Swagger描述端点 /v2/api-docs

  • 使用 swagger2markup-maven-plugin ,将 /v2/api-docs 生成ASCIIDOC文件;

  • 使用 asciidoctor-maven-plugin ,将ASCIIDOC文件转换成HTML;

  • 部署

必备依赖

<!-- swagger -->
<!-- 之所以要排除,是因为如果不排除会报NumberFormatException的警告。 -->
<!-- 参考: 
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
  <exclusions>
    <exclusion>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-annotations</artifactId>
    </exclusion>
    <exclusion>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-models</artifactId>
    </exclusion>
  </exclusions>
  </dependency>
  <dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
  </dependency>
  <dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-annotations</artifactId>
  <version>1.5.21</version>
  </dependency>
  <dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-models</artifactId>
  <version>1.5.21</version>
  </dependency>
  • Swagger配置就省略了...

  • 代码里注解这样用(手动备忘)

11

@RestController
@RequestMapping("/notices")
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
@Api(tags = "公告相关接口", description = "公告相关接口")
public class NoticeController {
    /**
     * 查询最新的一条公告
     *
     * @return 公告列表
     */
    @GetMapping("/newest")
    @ApiOperation(value = "查询最新的一条公告", notes = "用于:公告")
    public Notice findNewest() {
        return new Notice();
    }}
    
    @AllArgsConstructor
    @NoArgsConstructor
    @Builder
    @Data
    @ApiModel("公告")
    public class Notice {
  /**
   * ID
   */
  @ApiModelProperty("id")
  private Integer id;

  /**
   * 公告内容
   */
  @ApiModelProperty("公告内容")
  private String content;
  ...}

生成ASCALL DOC

  • POM增加以下内容

<build>
  <plugins>
    <plugin>
      <groupId>io.github.swagger2markup</groupId>
      <artifactId>swagger2markup-maven-plugin</artifactId>
      <version>1.3.1</version>
      <configuration>
        <!-- api-docs访问url -->
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <!-- 生成为单个文档,输出路径 -->
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <config>
          <!-- ascii格式文档 -->
          <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
          <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
      </configuration>
    </plugin>
    ...


生成HTML文档

  • POM增加以下内容

<build>
  <plugins>
    <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>1.5.6</version>
      <configuration>
        <!-- asciidoc文档输入路径 -->
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <!-- html文档输出路径 -->
        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <!-- html文档格式参数 -->
        <attributes>
          <doctype>book</doctype>
          <toc>left</toc>
          <toclevels>3</toclevels>
          <numbered></numbered>
          <hardbreaks></hardbreaks>
          <sectlinks></sectlinks>
          <sectanchors></sectanchors>
        </attributes>
      </configuration>
    </plugin>

  • 最后,别忘了执行:mvn swagger2markup:convertSwagger2markup

  • 插件 asciidoctor-maven-plugin

地址:https://github.com/asciidoctor/asciidoctor-maven-plugin

标签: 后端 文档 swagger

发表评论 (已有0条评论)

还木有评论哦,快来抢沙发吧~