Swagger2 生成静态Markdown文档

通过ui界面使用Swagger

在Springboot中,Swagger2 可以通过使用注解的方式,自动的生成API接口文档,同时它自带接口测试的功能,开发时可以给前后端交互带来极大的便利.

如下代码:

@Api(tags = "主页的接口")
@RestController
@RequestMapping("/home")
public class HomeController {

    @Resource
    ArticleService articleService;

    @Resource
    TokenUtil tokenUtil;

    @ApiOperation("获取首页文章")
    @AdminPermission(validate = false)
    @GetMapping("/articles")
    public Result getSimpleArticles(@RequestParam(name = "title",required = false)String title, @RequestHeader(value = "token", required = false)String token, @RequestParam("page") int page, @RequestParam("limit")int limit){
        if(tokenUtil.isTokenAvalible(token)){
            return articleService.selectSimpleArticles(title, true, page, limit);
        }
        return articleService.selectSimpleArticles(title, false, page, limit);
    }

}

将会生成如下的界面:

批注 2020-07-11 190306.png

界面中有接口的名称,并且在需要传递json对象时将自动列出需要的格式,开发人员不需要再自己去找对应的实体类,只需要填入对应的json内容即可.

生成静态的Markdown文档

ui界面虽然方便,并且自带测试功能,但是有时候在应用没有开启的时候,swagger自然也不会开启,这时就需要离线文档.

我们需要先导入jar包,pom如下:

 <dependencies> 
     ...
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
 </dependencies>
 <repositories>  
     <!--这里比较重要,少了可能找不到jar包-->
        <repository>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>always</updatePolicy>
            </snapshots>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
        </repository>
    </repositories>

一个坑

上面的pom中,必须添加指定的repository,不能使用aliyun的仓库(之前就是在这里卡了很久),使用aliyun的仓库会有两个jar包找不到,导致不能正常使用.

启动类

 @Test
    public void generateMarkdownDocs() throws Exception {
        //    输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8081/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/markdown/generated"));
    }

在上述的启动类中,必须要填写正确的url,我们可以首先测试一下页面是否能正常访问,如果打开后是正常的json页面,则可以进行下一步:

正常的页面: