当前位置：网站首页>Swagger: how to generate beautiful static document description pages

Swagger: how to generate beautiful static document description pages

2022-06-26 20:12:00 【A rookie is a great God】

effect

Uploading … Re upload cancel

The overall steps

Integrate Swagger, Generate Swagger Describe the endpoint /v2/api-docs
Use swagger2markup-maven-plugin , take /v2/api-docs Generate ASCIIDOC file ;
Use asciidoctor-maven-plugin , take ASCIIDOC File conversion to HTML;
Deploy

Integrate Swagger

TIPS
Swagger Is very simple to use , This article will not discuss , Please check the usage of Baidu by yourself .
Commonly used annotations ：
@Api
@ApiOperation
@ApiModel
@ApiModelProperty

Plus dependence

<!-- swagger -->
<!--  The reason to exclude , It is because if it is not excluded, it will report NumberFormatException Warning of . -->
<!--  Reference resources ：https://github.com/springfox/springfox/issues/2265-->
<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>

To configure Swagger（ Configure according to your own needs , The following configuration codes are for reference only ）

/**
 * @author itmuch.com
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    /**
     * swagger  Information 
     *
     * @return  Page information 
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ITMuch API")
                .description("ITMuch API")
                .termsOfServiceUrl("")
                .version("1.0.0")
                .contact(new Contact("", "", "")).build();
    }

    @Bean
    public Docket customImplementation() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.itmuch"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(this.apiInfo());
                //.globalOperationParameters(parameters);
    }
}

Interface for Swagger annotation

@RestController
@RequestMapping("/notices")
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
@Api(tags = " Announcement related interfaces ", description = " Announcement related interfaces ")
public class NoticeController {
    /**
     *  Check the latest announcement 
     *
     * @return  Announcement list 
     */
    @GetMapping("/newest")
    @ApiOperation(value = " Check the latest announcement ", notes = " be used for ： Notice ")
    public Notice findNewest() {
        return new Notice();
    }
}


@AllArgsConstructor
@NoArgsConstructor
@Builder
@Data
@ApiModel(" Notice ")
public class Notice {
  /**
   * ID
   */
  @ApiModelProperty("id")
  private Integer id;

  /**
   *  Announcement content 
   */
  @ApiModelProperty(" Announcement content ")
  private String content;
  ...
}

such , After the application is started , There will be one /v2/api-docs Endpoint , Describe your API Information about .

Generate ASCIIDOC

stay pom.xml To add the following ：

<build>
  <plugins>
    <plugin>
      <groupId>io.github.swagger2markup</groupId>
      <artifactId>swagger2markup-maven-plugin</artifactId>
      <version>1.3.1</version>
      <configuration>
        <!-- api-docs visit url -->
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <!--  Generate as a single document , The output path  -->
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <config>
          <!-- ascii Format document  -->
          <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
          <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
      </configuration>
    </plugin>
    ...

swagger2markup-maven-plugin The function of the plug-in is to read http://localhost:8080/v2/api-docs Information about , Generate ASCIIDOC file . Of course, you can also generate other formats , such as Markdown wait .

This plug-in also has a lot of gestures , See https://github.com/Swagger2Markup/swagger2markup-maven-plugin

Generate HTML

below , Only need to ASCIIDOC convert to html Just OK 了 , stay pom.xml To add the following ：

<build>
  <plugins>
    <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>1.5.6</version>
      <configuration>
        <!-- asciidoc Document input path  -->
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <!-- html Document output path  -->
        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <!-- html Document format parameters  -->
        <attributes>
          <doctype>book</doctype>
          <toc>left</toc>
          <toclevels>3</toclevels>
          <numbered></numbered>
          <hardbreaks></hardbreaks>
          <sectlinks></sectlinks>
          <sectanchors></sectanchors>
        </attributes>
      </configuration>
    </plugin>

asciidoctor-maven-plugin The plug-in also has many poses , See ：GitHub - asciidoctor/asciidoctor-maven-plugin: A Maven plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.

The generated file is in src/docs/asciidoc/html （ Look at the configuration of your plug-in ）, Then you can get a NGINX Deployed .