Swagger
-
Swagger是什么?
- 简单的来说就是一款自动生成API文档并且支持在线调试的一个十分实用的工具。
- 通过Swagger规定的规范去定义接口几接口相关的信息,再通过Swagger衍生出来的一系列项目和工具,就可以生成各种格式的接口文档。
对于程序员来说,最难受的就是需要自己写接口文档等一系列其他文档,但是最最难受的就是别人不写文档。
尤其是现在对于前后端分离,如果接口调用不同意,一会儿加一个字段一会儿少一个字段,那真的是会分分钟要人命。
所以出现了Swagger,这个可以用于生成,描述,调用和可视化RESTful风格的Web服务。
总的来说,Swagger的功能就两个:
- 接口的文档在线自动生成
- 功能测试
SpringBoot集成Swagger
- 引入依赖
<!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>版本号需要注意</version> </dependency> <!-- swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>版本号需要注意</version> </dependency>
相关配置
```
server:
port: 8080
servlet:
context-path: /
spring:
datasource:
url: jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=UTF-8&zeroDateTimeBehavior=convertToNull&allowMultiQueries=true&useSSL=false
username: root
password: 123456
jpa:
database: MySQL
database-platform: org.hibernate.dialect.MySQL5InnoDBDialect
show-sql: true
hibernate:
ddl-auto: update
```
- 使用注解来启动Swagger,同时需要进行配置
@Configuration @EnableSwagger2 public class SwaggerConfig{ //一个Docket就是一组Group @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //为当前包路径 .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } //构建 api文档的详细信息函数,注意这里的注解引用的是哪个 private ApiInfo apiInfo() { return new ApiInfoBuilder() //页面标题 .title("标题") //创建人 .contact(new Contact("名字", "url", "")) //版本号 .version("1.0") //描述 .description("描述") .build(); } }
- 配置Controller
也就是需要在Controller类上加上各种各样辅助生成API接口文档的注释
常见的注释使用:
注释 | 作用 | 使用方式 | 参数 |
---|---|---|---|
@Api | 标识这个类是Swagger的资源 | 用于类 | tags:表示说明,value:也是表示说明 |
@ApiModel | 对类进行说明,用于参数用实体类接收 | 用于实体类 | value:表示对象名,description:描述 |
@ApiOperation | 标识一个http请求的操作 | 用于方法 | value:方法描述,notes:提示内容,tags:可以重新分组 |
@ApiImplicitParams | 表示单独的请求参数 | 用于方法 | name:参数名,value:参数说明,dataType:数据类型,paramType:参数类型,example:举例说明 |
@ApiParam | 标识对参数添加元素据 | 用于方法,参数,字段 | required:是否必须填写,name:参数名,value:参数说明 |
产生的结果:需要通过访问 你的主机地址例如 http://localhost:8080/swagger-ui.html
就会产生这样的效果。
基本的Swagger的使用就是这样了。
Swagger注解是其中的关键,引入的是此处的图片的一张图: