项目的swagger2对外开放API文档的开发和使用
Swagger 是比较流行的 API 开发工具，是一种通用的，和编程语言无关的 API 描述规范；
JAVA项目里面加上Swagger之后，就不用再另外去花时间编写后端API接口文档了；
pom.xml文件中加上以下依赖包，加入的代码如下：
io.springfox
springfox-swagger2
2.4.0
io.springfox
springfox-swagger-ui
2.4.0
并且将pom.xml文件中的：
org.springframework.boot
spring-boot-starter-parent
2.6.6
中的2.6.6改为2.4.0；
如下图1和2：
然后点击右上角更新架包；
如下图3：
增加配置文件SwaggerConfig，在类上加上@Configuration和@EnableSwagger2，
@Configuration是为了让项目把此类文件当做配置类文件进行读取；
@EnableSwagger2是为了启动Swagger2；
并增加以下代码：
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.yydpt.base"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot-Mybatis-Swagger 对外开放接口API 文档")
.contact("月影")
.version("1.0.0")
.termsOfServiceUrl("http://www.yydpt.com")
.license("LICENSE")
.licenseUrl("http://www.yydpt.com")
.build();
}
如下图所示：
图4
访问接口是：http://localhost:8080/swagger-ui.html
效果图如下：
图5
然后创建控制器UserController，并加上以下代码：
图6
图6中代码详解：
@Api
作用: 用来指定接口的描述文字；
修饰范围: 用在类上；
@ApiResponses
作用：用于请求的方法上，表示一组响应；
修饰范围: 用在方法上；
@ApiOperation
作用：用在请求的方法上，说明方法的用途、作用；
修饰范围: 用在方法上；
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
页面效果如下：
图7
图8
在图8中的username和password的后面输入字段值之后，点击Try it out！可以测试该接口的情况；
这样一个JAVA项目的API接口文档就做好了，剩下的就是在每一次写接口的时候加上对应需要的注释即可；
好处就是以后前端再找后端要接口和接口参数的时候，后端直接把这个接口文档发给前端，让他自己去看；
以后也不用再去额外的整理项目中接口的使用情况了，直接就能在此接口文档中看到所有的接口信息了；
不过这个接口文档的样式是不是不太美观呀，这个也挺好处理的，可以通过swagger-bootstrap-ui这个依赖包优化样式，这个就下次讲解了；
关注微信公众号（月影WEB），了解更多的前后端知识；
欢迎大家关注互相交流学习；
