君子性非异也 善假于物也(二) springboot整合swagger-fox,告别写代码的同时去维护一份多余的接口文档

swagger-fox的官方文档 ，http://springfox.github.io/springfox/docs/current/  我这里只是简单介绍

首先说为什么要用swagger，因为人生苦短啊

1. 初期考虑过从注释里面生成的文档，但是javadoc太丑，遂弃之。

2. swagger可拓展性高,可以直接从接口中拿到所有接口的json格式数据，官方也提供了直接解析的工具包https://github.com/swagger-api/swagger-parser ,很齐全了，配合起来自己可以生成markdown，asicc之类的文档，还可以放在confluence上面，不过confluence对markdown的支持太水了，很多格式都没法搞。

这里介绍一个maven的插件，项目启动后就可以直接运行生成markdown格式的接口文档，不过我觉得文档里面自动生成的不够简洁，所以自己花了两个小时写了一个，很快的，这里只放上该插件了，用不用自己可以试一下。

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <!-- api-docs访问url -->
        <swaggerInput>http://localhost:61022/v2/api-docs</swaggerInput>
        <!-- 生成为单个文档，输出路径 -->
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <!-- 生成为多个文档，输出路径 -->
        <!--<outputDir>src/docs/asciidoc/generated</outputDir>-->
        <config>
            <!-- wiki格式文档 -->
            <!--<swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage>-->

            <!-- ascii格式文档 -->
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>

            <!-- markdown格式文档 -->
            <!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
    </configuration>
</plugin>

3. 有现成的UI界面(不好看，也不算丑，够用了)

下面正式介绍怎么搭建了，废话不多说，直接上maven配置

<!--swagger-->
<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>

在spring启动的Main类中要加上

在springboot项目中加入swagger配置，也有更多的自定义和详细的配置去看官方文档吧

@Configuration
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.anyang.web.book.controller"))
                .build()
                .useDefaultResponseMessages(false);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("金管家文档")
                .description("金管家文档")
                .version("1.0")
                .build();
    }
}

下面就可以直接访问了

{baseurl}/swagger-ui.html 即可访问

{baseurl}/v2/api-docs 获取所有接口的json数据