一,简介
什么是swagger?我们去官网看一下https://swagger.io/:简化Api开发,方便大规模Api设计。
- 号称世界上最流行的Api框架。
- RestFul Api文档在线生成工具。
- 直接运行,可以在线测试Api接口。
- 支持多种语言,java、php等。
二、如何使用Swagger
1.基本配置
使用swagger需要引入两个包,一个是核心包一个是前端展示的包。.
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
由于不是springBoot内置的starter所以我们需要,自定义配置文件,将swagger的实力Docket,交给springboot管理。
package com.swagger.controller.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* swagger配置信息
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* Swagger必须配置的Docket 实例
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//groupName 配置当前接口的分组
.groupName("cp的接口")
//配置是否启用swagger false不启动
// .enable(false)
//配置需要扫描的接口包
.select().apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
//需要过滤的包路径
// .paths(PathSelectors.ant(""))
.build();
}
/**
* Swagger必须配置的Docket 实例
* 可以配置多个实例,代表多个分组,
*/
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//groupName 配置当前接口的分组
.groupName("小张的接口")
//配置是否启用swagger false不启动
// .enable(false)
//配置需要扫描的接口包
.select().apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
//需要过滤的包路径
// .paths(PathSelectors.ant(""))
.build();
}
/**
* swagger页面基本展示信息
* @return
*/
private ApiInfo apiInfo(){
return new ApiInfo(
"c_pown Test Api",
"c_pown Test Api", "1.0",
"urn:tos",
new Contact("cp", "www.baidu.com", "952793966@qq.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0");
}
}
- 首先我们需要定义swagger页面基本展示信息,也就是ApiInfo,这里可以定义项目名称,公司名称,项目版本号等信息。可以在项目启动后访问http://localhost:8080/swagger-ui.html查看。
- 配置Swagger的
Docket
实例,一个Docket
可以说代表一个分组,可以是开发小组,也可以是个人。
通过Docket构造定义信息:
.groupName:配置当前接口的分组 ;
.enable:配置是否启用swagger false不启动;
.apis(RequestHandlerSelectors.basePackage(“com.swagger.controller”)):配置当前的接口所在包名。
.paths(PathSelectors.ant("")):不需要生成接口文档的包路径。
这里我们配置了两个Docket实例可以看到页面是有两个分组:
2.接口编写
package com.swagger.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户")
public class SysUser {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
public SysUser() {
}
public SysUser(String username, String password) {
this.username = username;
this.password = password;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
package com.swagger.controller;
import com.swagger.pojo.SysUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
@Api(tags = {"我的接口"} ,description = "我的接口Controller")
@RestController
public class Controller {
/**
* 定义接口最好使用GetMapping、PostMapping
* 使用RequestMapping 会在页面生成多种接口
* @return
*/
@ApiOperation("欢迎页面接口")
@GetMapping("/hello")
public String helloword(@ApiParam("用户名")@RequestParam("username") String username){
return "hello"+username;
}
/**
* 如果使用
*/
@ApiOperation("user接口")
@PostMapping("/user")
public SysUser user( SysUser sysUser){
return new SysUser("张三","李四");
}
/**
* 最好不要使用RequestMapping
* @param username
* @return
*/
@ApiOperation("最好不要使用")
@RequestMapping("/RequestMapping")
public String sss(@ApiParam("用户名")@RequestParam("username") String username){
return "hello"+username;
}
}
- @ApiModel(“用户”) :给实体类名添加swagger文档注释
- @ApiModelProperty(“用户名”):给实体类字段添加swagger文档注释
- @Api(tags = {“我的接口”} ,description = “我的接口Controller”):给接口类添加名称和注释
- @ApiOperation(“欢迎页面接口”):给接口添加名称
注意:这里最好不要使用@RequestMapping
,因为RequestMapping既可以接收Get请求也可以接收Post请求,生成文档会生产多种请求。
使用@GetMapping 或者 @PostMapping指定请求类型。
我们看一下页面:
可以直接点击接口进行测试,方便又快捷:
可以直接输入参数,点击try it on
进行接口测试。