Spring boot 集成 swagger生成api文档（转换成markdown格式）

spring boot 集成 swagger

步骤

1. 导入jar包
2. 添加配置类
3. 添加接口类
3. 启动服务器
4. 访问UI页面,可在线测试接口
5. 导出swagger源文件
6. 转换成markdown格式文件

1，导入jar包
gradle方式
compile 'io.springfox:springfox-swagger2:2.6.1'
compile 'io.springfox:springfox-swagger-ui:2.6.1'

maven方式

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

2，添加配置类

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;

/**
 * @author hanxu
 * @ClassName swagger2
 * @Description
 * @date 2017-07-10 22:12:31
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zxg.qgg"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ZXG-在线API文档")
                .description("杭州纸箱哥广告传媒有限公司")
                .termsOfServiceUrl("http://www.zhixiangge.com/")
                .version("1.0")
                .build();
    }
}

3，添加接口类（主要看注解，参照官网）

@ApiOperation(value = "根据分类id分页查询文章")
@ApiImplicitParams({
        @ApiImplicitParam(name = "articleId", value = "分类id", required = true, dataType = "Long", paramType = "query"),
        @ApiImplicitParam(name = "pageNum", value = "pageNum", required = true, dataType = "Long", paramType = "query"),
        @ApiImplicitParam(name = "pageSize", value = "pageSize", required = true, dataType = "Long", paramType = "query")
})
@GetMapping("list")
public R queryAll(@RequestParam Map<String, Object> params) {
    return R.ok().data(cmsArticlePageInfo);
}

4，启动服务器

5，访问UI页面

http://localhost:8080/swagger-ui.html

访问http://localhost:8080/v2/api-docs可以得到json数据

访问http://editor.swagger.io/可以将json数据转换成yaml文件并下载到本地

转换成markdown格式文件

1.导入jar包

gradle方式

compile 'io.github.swagger2markup:swagger2markup:1.3.1'

maven方式

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.1</version>
</dependency>

2.添加转换类

public static void main(String[] args) throws Exception {
    Path outputFile = Paths.get("build/swagger");
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
            .withMarkupLanguage(MarkupLanguage.MARKDOWN)
            .withOutputLanguage(Language.ZH)
            .withPathsGroupedBy(GroupBy.TAGS)
            .withGeneratedExamples()
            .withoutInlineSchema()
            .build();
    Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
            .withConfig(config)
            .build();
    converter.toFile(outputFile);
}

3.排除jar包冲突(导入了swagger的两个jar包后再导入转markdown的jar包，其中有个swagger-models会有问题，要排除一下)

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Spring boot 集成 swagger生成api文档（转换成markdown格式）

猜你喜欢