之前的文章有讲过Swagger2对外开放API文档的开发和使用,可能UI没那么好看,这次我们使用swagger-bootstrap-ui这个架包文件;
通过swagger-bootstrap-ui可以让对外开发文档的页面UI更加美观;
下面是效果图:
图0
pom.xml文件中加上以下依赖包,加入的代码如下:
<!--Swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger-bootstrap-ui-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
如下图:
图1
然后点击右上角更新架包;
图2
增加配置文件SwaggerConfig,在类上加上@Configuration和@EnableSwagger2,
@Configuration是为了让项目把此类文件当做配置类文件进行读取;
@EnableSwagger2是为了启动Swagger2;
并增加以下代码:
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("base")
.select()
// 要扫描的API(Controller)基础包
.apis(RequestHandlerSelectors.basePackage("com.yydpt.base"))
// 要扫描的API(Controller)全局-(就是可以扫描所有的带有api注解的包并生成文档)
// .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
//配置在线文档的基本信息
private ApiInfo apiInfo() {
Contact contact = new Contact("月影", "http://www.yydpt.com","363284801@qq.com");
return new ApiInfoBuilder()
.title("接口API 文档")
.description("SpringBoot-Mybatis-Swagger-SwaggerBootstrapUI 对外开放接口API 文档")
.contact(contact)
.version("1.0.0")
.termsOfServiceUrl("http://www.yydpt.com")
.license("LICENSE")
.licenseUrl("http://www.yydpt.com")
.build();
}
如下图所示:
图3
访问接口是:http://localhost:8080/doc.html
效果图如下:
图4
然后创建控制器UserController,并加上以下代码:
图5
图5中代码详解:
@Api
作用: 用来指定接口的描述文字;
修饰范围: 用在类上;
@ApiResponses
作用:用于请求的方法上,表示一组响应;
修饰范围: 用在方法上;
也可以作用在类上,当它作用在类上面的时候,类里面的所有方法均会有对应的响应;
@ApiOperation
作用:用在请求的方法上,说明方法的用途、作用;
修饰范围: 用在方法上;
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
页面效果如下:
图6
图7
图8
图9
在图9中的username和password的后面输入字段值之后,点击“发送”可以测试该接口的情况;
这样一个JAVA项目的API接口文档就做好了,剩下的就是在每一次写接口的时候加上对应需要的注释即可;
好处就是以后前端再找后端要接口和接口参数的时候,后端直接把这个接口文档发给前端,让他自己去看;
以后也不用再去额外的整理项目中接口的使用情况了,直接就能在此接口文档中看到所有的接口信息了;
关注微信公众号(月影WEB),了解更多的前后端知识;
欢迎大家关注互相交流学习;