文档！重要的事情说第四遍~

Posted 2020-08-09 风间影月の技术小站

之前我有提过文档的事，标题是《文档！文档！文档！重要的事情说三遍！》，其中提到的文档工具是使用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吧，十分简单，非常适合小团队开发