推荐导航
一.概述
文档向来在软件开发过程中的每一个阶段都是非常重要的,如果没有文档,那软件的可维护性就会变得很糟,以致于影响可扩展性,最后慢慢的使软件变成一堆乱糟糟的无用的代码。而不同系统之间的接口文档其重要性更显而易见,一般常用的接口文档采用以下形式:
- 口口相传
- 用world或其他文本文件进行保存
- 用wiki编写
上面这些方式都有各自的缺点,比如不易维护,不易测试接口,接口变更而文档未能同步更新等。但Swagger的出现改变了这些情形,Swagger的文档编写相当于就是在写代码,在更改接口代码的同时就能方便的更新文档,还能方便的进行接口的测试。
二.入门案例
-
先创建号springboot的web项目 (详细见springboot的入门)
-
导入swagger的jar
<!-- swagger2 api文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- 编写配置
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.groupName("RestApi") //组
.select()
.apis(RequestHandlerSelectors.basePackage("com.ganyz.springcloudproducer.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(new ApiInfoBuilder()
.title("springboot 整合 swagger")//接口文档的标题
.description("springboot 整合 swagger test")
.version("test 01")
.contact(new Contact("name", "url", "email")) // 开发文档的作者信息
.license("license") //license 规范
.licenseUrl("licenseUrl")
.build());
}
// Docket:如果需要分组显示不同文件夹下的controller,则写多个, 否则只需要写上面一个Docket就好了
@Bean
public Docket createRestCopyApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.groupName("RestCopyApi")//组
.select()
.apis(RequestHandlerSelectors.basePackage("com.ganyz.springcloudproducer.controllerCopy"))
.paths(PathSelectors.any())
.build()
.apiInfo(new ApiInfoBuilder()
.title("springboot 整合 swagger")//接口文档的标题
.description("springboot 整合 swagger test")
.version("test 01")
.contact(new Contact("name", "url", "email")) // 开发文档的作者信息
.license("license") //license 规范
.licenseUrl("licenseUrl")
.build());
}
}
4.书写controller
package com.ganyz.springcloudproducer.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
/**
* @date 2021/5/11
*/
@Api(tags = "用户服务接口swagger")
@Controller
@RequestMapping("swagger2All")
public class SwaggerHelloWorldController {
@ApiOperation(value = "查询:swagger", notes = "查询swagger的接口") // value: 请求路径后面的解释;
@RequestMapping("/swagger")
@ResponseBody
public String swagger(){
System.out.println("swagger=====");
return "swagger";
}
}
@Controller
public class HelloWorldController {
@RequestMapping("/hello")
@ResponseBody
public String hello(){
System.out.println("hello=====");
return "hello";
}
}
- 请求页面地址
地址:http://localhost:10212/swagger-ui
三.注释介绍
- @Api() 用在请求的类上,表示对类的说明,也代表了这个类是swagger2的资源
tags:说明该类的作用,参数是个数组,可以填多个。
value=“该参数没什么意义,在UI界面上不显示,所以不用配置”
description = “用户基本信息操作”
- @ApiOperation():用于方法,表示一个http请求访问该方法的操作
value=“方法的用途和作用”
notes=“方法的注意事项和备注”
tags:说明该方法的作用,参数是个数组,可以填多个。
格式:tags={“作用1”,“作用2”}
(在这里建议不使用这个参数,会使界面看上去有点乱,前两个常用)
- @ApiModel():用于响应实体类上,用于说明实体作用
description=“描述实体的作用”
- @ApiModelProperty() 用在属性上,描述实体类的属性
value=“用户名” 描述参数的意义
name=“name” 参数的变量名
required=true 参数是否必选
四.swagger替换ui界面
- 关于spring boots中使用swagger-bootstrap-ui 替换默认ui, 导入如下jar
<!-- swagger2 api文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- spring boots中使用swagger-bootstrap-ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.8.3</version>
</dependency>
访问地址: http://localhost:10212/doc.html