一、所需要的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。
六、我所看到的其他swagger优秀博客
http://www.cnblogs.com/yuananyun/p/4993426.html
https://blog.csdn.net/y534560449/article/details/53694443
https://www.cnblogs.com/woshimrf/p/5863318.html
https://blog.csdn.net/w4hechuan2009/article/details/68892718
https://blog.csdn.net/jun55xiu/article/details/70316851
与诸君分享!!
七.一些问题
1.如何让这些列表正常排序.?
排序是按照@Api.value字典顺序进行排序的,但是tags会覆盖掉value
2.接口列表无法单击展开
原因是@Api.tags使用了中文,如果想要中文说明描述,请使用那个@Api.discrption