swagger生成markdown

用swagger生成离线的markdown文档

一、pom

		<swagger.version>2.8.0</swagger.version>
		<!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.6</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

二、配置类(注意basePackage路径)

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger2配置类.
 *
 * @author dlz
 * @version 1.0.0
 * @date 2021/6/2 15:20
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
  /**
   * bean生成.
   *
   * @return Docket
   */
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(getApiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.lin.test.controller"))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo getApiInfo() {
    return new ApiInfoBuilder()
        .title("我的API")
        .description("************************描述************************")
        .version("1.0")
        .license("Apache 2.0")
        .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
        .build();
  }
}

三、测试类(注意项目访问路径)

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import java.net.URL;
import java.nio.file.Paths;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

@SpringBootTest
@RunWith(SpringRunner.class)
public class Documentation {

  /**
   * 生成Markdown格式文档,并汇总成一个文件.
   *
   * @throws Exception 异常
   */
  @Test
  public void generateMarkdownDocsToFile() throws Exception {
    //    输出Markdown到单文件
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.MARKDOWN)
        .withOutputLanguage(Language.ZH)
        .withPathsGroupedBy(GroupBy.TAGS)
        .withGeneratedExamples()
        .withoutInlineSchema()
        .build();

    String swaggerUrl = "http://localhost:8040/v2/api-docs";
    Swagger2MarkupConverter.from(new URL(swaggerUrl))
        .withConfig(config)
        .build()
        .toFile(Paths.get("src/docs/md")); 
  }
}

四、使用

• 实体类

@Data
@EqualsAndHashCode
@Accessors(chain = true)
@ApiModel(value = "DeviceTrack对象", description = "device_track")
public class DeviceTrack implements Serializable {
  @ApiModelProperty(value = "所属行程id")
  private Long tripId;
  @ApiModelProperty(value = "设备id")
}

• 接口

@Api(tags = "DeviceTrackController")
@RestController
@RequestMapping("/device-track")
public class DeviceTrackController {
  @ApiOperation(value = "getDeviceTracks", notes = "根据行程id，查询对应的轨迹数据，分页返回")
  @GetMapping("getDeviceTracks")
  public Result getDeviceTracks(@ApiParam(value = "行程id", required = true) Long tripId,
                                @ApiParam(value = "当前页", defaultValue = "1") Integer curPage,
                                @ApiParam(value = "页量", defaultValue = "100") Integer pageSize) {
                                }

五、生成

运行测试类，会在src/docs/md下生成md命令，复制纯文本到Typora即可