介绍
在前后端分离开发中通常由后端程序员设计接口,完成后需要编写接口文档,最后将文档交给前端工程师,前端工程师参考文档进行开发。
可以通过一些工具快速生成接口文档 ,例如Swagger生成接口在线文档 。
什么是Swagger?
OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程,目前版本是V3.0,并且已经发布并开源在github上。
(https://github.com/OAI/OpenAPI-Specification)
Swagger是全球最大的OpenAPI规范(OAS)API开发工具框架,Swagger是一个在线接口文档的生成工具,前后端开发人员依据接口文档进行开发。 (API Documentation & Design Tools for Teams | Swagger)
Spring Boot 可以集成Swagger,Swaager根据Controller类中的注解生成接口文档 ,只要添加Swagger的依赖和配置信息即可使用它。
使用
首先导入pom
<!-- Spring Boot 集成 swagger -->
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
</dependency>
在yml配置文件中加入
#http://localhost:63042/content/swagger-ui.html
swagger:
title: "线上课程平台"
description: "内容系统管理系统对课程相关信息进行管理"
base-package: com.example.content
enabled: true
version: 1.0.0
在启动类上加注解@EnableSwagger2Doc
@EnableSwagger2Doc
@SpringBootApplication
public class CoursePlatformContentApiApplication {
public static void main(String[] args) {
SpringApplication.run(CoursePlatformContentApiApplication.class, args);
}
}
在浏览器输入 #http://localhost:63042/content/swagger-ui.html 即可进入
在接口文档中加入标注
只需要在需要标注的字段上加@ApiModelProperty("标注内容") 注解即可
Swagger常用注解
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
解决乱码
打开settings修改