一、所需要的jar包（如果是普通web工程的话），这个还是非常多非常恶心的。

二、如果是pom文件的话，就比较少，maven会自动下载相关依赖，核心依赖就下面这些

<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-webmvc</artifactId>
			<version>4.2.8.RELEASE</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind -->
		<dependency>
		    <groupId>com.fasterxml.jackson.core</groupId>
		    <artifactId>jackson-databind</artifactId>
		    <version>2.9.5</version>
		</dependency>
		
		<!-- swagger2核心依赖 -->

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

		<!-- swagger-ui为项目提供api展示及测试的界面 -->

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

三、先搭好一个SpringMvc的框架。然后新建个类如下：

@EnableWebMvc
@EnableSwagger2
public class ApiConfig {}

这是一个空的类。然后把这个类做成bean，配置到Springmvc.xml文件里面去。

启动起来后，这时候接口文档就可以直接使用了。

打开http://localhost:8080/${projectName}/swagger-ui.html.这里的projectName就是你的工程名，如果放到tomcat的Root下面那就不用写了。这时候打开应该是这样的。

非常刺激对不对？为什么？我也不知道。

四、让我们的接口文档化。这需要我们了解几个常用注解

我们写个controller

/**
 * @Api 这个注解分模块的,记得要用tags
 * @author dumingwei
 *
 */
@Api(tags="用户模块")
@RestController
@RequestMapping("/user")
public class UserController {
	/**
	 * @ApiOperation 这个注解是指该方法是用来做什么的,一定要加上httpMethod,否则会出现一堆
	 * @param userVo
	 * @return
	 */
	@ApiOperation(value = "查看用户",httpMethod="POST")
	@RequestMapping("findUser")
	public Result findUser(UserVo userVo){
		System.out.println(userVo.getId());
		return new Result();
	}
}

我们来看看效果

OK，已经出来了。但是有时候这个id和username并不会被展开，而是一个Body的样子，那么这时候我们要在参数上加个注解

就会自动解开。

@ApiOperation(value = "查看用户",httpMethod="POST")
	@RequestMapping("findUser")
	public Result findUser(@ModelAttribute UserVo userVo){
		System.out.println(userVo.getId());
		return new Result();
	}

那么如果这个参数对象我不想暴露怎么办？我只想接受其中的某个参数值，其他的并不想展露出来给API文档呢？

那这时候就要忽略掉参数对象了，而是自行添加参数详情。

@ApiOperation(value = "修改用户",httpMethod="POST")
	@ApiImplicitParams({
		@ApiImplicitParam(name="userid",value="用户id",required=false,paramType="query")
	})
	@RequestMapping("updateUser")
	public Result updateUser(@ApiIgnore UserVo userVo){
		System.out.println(userVo.getId());
		return new Result();
	}

这里使用了@ApiIgnore的注解，忽略。

这个注解不仅可以忽略参数，也可以加在方法上忽略掉url,让某些url不出现在API列表里面。

五、详细配置。

@ApiIgnore可以做到忽略，但是如果我们不想暴露的接口API比较多，那么给每个添加就不太合适了。所以这里我们要回到开始的地方，那个空的类里去配置一些东西。

以下配置包含3种东西。

1.修改API页面的大小标题

2.修改API的包含路径正则，只针对正则里面的进行生成API

3.让每个访问都加入参数，我因为使用的是需要每个访问都要加入一个参数token。

@EnableWebMvc
@EnableSwagger2
public class ApiConfig {
	@Bean
	public Docket customDocket() {
		/**
		 * 设置参数token
		 */
		ParameterBuilder ticketPar = new ParameterBuilder();
		List<Parameter> pars = new ArrayList<Parameter>();
		ticketPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header")
				.required(false).build(); // header中的token参数非必填，传空也可以
		pars.add(ticketPar.build()); // 根据每个方法名也知道当前方法在设置什么参数

		/**
		 * 这里有包含正则
		 */
		return new Docket(DocumentationType.SWAGGER_2).select().
				apis(RequestHandlerSelectors.any()).
				/**
				 * 这里有路径匹配包含正则，这里就是只要url里包括app，那么就才可以生成文档
				 */
				paths(PathSelectors.regex(".*app.*")).
				build()
				/**
				 * 这里把token加进去了。
				 */
				.globalOperationParameters(pars).
				apiInfo(apiInfo());
	}
	/**
	 * 这个是设置大标题小标题
	 * @return
	 */
	ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("小妹小哥软件").description("前后端联调api 文档").version("0.1.0")
				.build();
	}
}

自己理解吧。我懂的也不是太多。但是这个足够用了。另外如果想要翻译的话，把swaggerfox-ui.jar包拆了替换下字符就可以了。

还有一个非常重要的事情，我们用的是swagger2，不是swagger1，用的是swaggerfox这个驱动包，不是其他的，一定不要导错包了，否则很惨的。我就因为导错包，怎么也搞不出效果废了一天。

还是想说一句MMP。