文檔！重要的事情說第四遍~，文檔事情

文檔！重要的事情說第四遍~，文檔事情

之前我有提過文檔的事，標題是《文檔！文檔！文檔！重要的事情說三遍！》，其中提到的文檔工具是使用wiki來管理文檔，當然也能配合jira來分發任務，以及管理bug，查看每個任務的工作流狀態等等

今天來講講另外一個文檔工具，swagger+spring，這個插件比較好用，非常適合那種敏捷開發的小團隊，不像wiki那麼繁瑣，更沒有word或者excel那麼難以管理，使用這個工具，你只需要在代碼中配置好相應的注解，在spring容器加載的時候就自動掃描進去了，使用非常方便，那麼先來簡單看看吧

​

首先需要配置pom，引入相應的jar包

<!-- swagger-springmvc -->
            <dependency>
                <groupId>com.mangofactory</groupId>
                <artifactId>swagger-springmvc</artifactId>
                <version>${mangofactory.swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>com.mangofactory</groupId>
                <artifactId>swagger-models</artifactId>
                <version>${mangofactory.swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>com.wordnik</groupId>
                <artifactId>swagger-annotations</artifactId>
                <version>${swagger-annotations.version}</version>
            </dependency>
            <!-- swagger-springmvc dependencies -->
<!--             <dependency> -->
<!--                 <groupId>com.google.guava</groupId> -->
<!--                 <artifactId>guava</artifactId> -->
<!--                 <version>15.0</version> -->
<!--             </dependency> -->
            <dependency>
                <groupId>com.fasterxml.jackson.core</groupId>
                <artifactId>jackson-annotations</artifactId>
                <version>${jackson.version}</version>
            </dependency>
            <dependency>
                <groupId>com.fasterxml.jackson.core</groupId>
                <artifactId>jackson-databind</artifactId>
                <version>${jackson.version}</version>
            </dependency>
            <dependency>
                <groupId>com.fasterxml.jackson.core</groupId>
                <artifactId>jackson-core</artifactId>
                <version>${jackson.version}</version>
            </dependency>
            <dependency>
                <groupId>com.fasterxml</groupId>
                <artifactId>classmate</artifactId>
                <version>${classmate.version}</version>
            </dependency>

配置好SwaggerConfig這個類，內容如下：

package com.dingli.rest.config;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;


/**
 * 
 * @Title: SwaggerConfig.java
 * @Package com.dingli.rest.config
 * @Description: SwaggerConfig 的配置，需要加入spring容器
 * Copyright: Copyright (c) 2016
 * Company:DINGLI.SCIENCE.AND.TECHNOLOGY
 * 
 * @author leechenxiang
 * @date 2016年9月14日 上午9:55:42
 * @version V1.0
 */
@Configuration
@EnableSwagger
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation() {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*?");
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title",
                "My Apps API Description",
                "My Apps API terms of service",
                "My Apps API Contact Email",
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}

然後你要去github上找到這個項目，然後下載後吧dlist中的所有內容導入到自己的項目中，在index.html中修改路徑，

http://petstore.swagger.io/v2/swagger.json";

這個是加載json，需要把這個段替換為你自己的地址："http://localhost:8080/swagger-ui.html"

最後訪問你就會得到對應的界面了

好了，OK，十分簡單的配置，但是絕提的接口對於參數等等，自己看api吧，十分簡單，非常適合小團隊開發