承接上文：
https://cloud.tencent.com/developer/article/2337666
本文是配置swagger的文章，版本是【2.9.2】
1、pom.xml的jar包引入
这里为了后文操作方便，我多添加了一个commons-lang3的包用于字符串的非空判断。
代码语言：javascript复制 <!-- swagger包这里2.9.2 -->
<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>
<!-- 用作字符串非空判断 -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.12.0</version>
</dependency>
2、创建【com.item.swagger】的配置文件【SwaggerConfig.java】
代码语言：javascript复制package com.item.swagger;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
private static Logger log = LoggerFactory.getLogger(SwaggerConfig.class);
@Bean
public Docket createRestApi() {
log.info("进入到swagger的配置中");
return new Docket(DocumentationType.SWAGGER_2)
// 指定构建api文档的详细信息的方法：apiInfo()
.apiInfo(apiInfo())
.groupName("红目香薰·为大一孩子准备的")
.select()
// 指定要生成api接口的包路径，这里把controller作为包路径，生成controller中的所有接口
.apis(RequestHandlerSelectors.basePackage("com.item.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 构建api文档的详细信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 设置页面标题
.title("Spring Boot集成Swagger2接口总览")
// 设置接口描述
.description("Swagger接口")
// 设置联系方式
.contact(new Contact("测试swagger","https://laoshifu.blog.csdn.net/",""))
// 设置版本
.version("1.0")
// 构建
.build();
}
}配置文件在上文的代码中就可以看到，并且我写了很多注释，应该是可以帮助到大家的。
3、示例swagger注解写法
代码语言：javascript复制package com.item.controller;
import com.item.model.Users;
import com.item.service.UsersService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.List;
@Api("用户操作接口")
@RestController
@CrossOrigin
public class UsersController {
@Autowired
private UsersService usersService;
/**
* 获取所有信息
* @return
*/
@GetMapping("/GetInfoApi")
@ApiOperation(value = "获取信息",notes = "没啥留言的")
public Object GetInfoApi(){
List<Users> list=usersService.GetInfo();
HashMap<String,Object> map=new HashMap<String,Object>();
map.put("state",true);
map.put("msg","成功");
map.put("result",list);
return map;
}
@GetMapping("/GetName")
@ApiOperation(value = "获取信息",notes = "没啥留言的")
@ApiImplicitParams({
@ApiImplicitParam(name = "nickName",required = true,paramType = "query",dataType = "String",value = "通过昵称模糊查询")
})
public Object GetName(HttpServletRequest request,Model model){
String nickName = request.getParameter("nickName");
List<Users> list=usersService.SelectName(nickName);
HashMap<String,Object> map=new HashMap<String,Object>();
map.put("state",true);
map.put("msg","成功");
map.put("result",list);
return map;
}
/**
* 添加信息
* @param userName
* @param pwd
* @param nickName
* @return
*/
@PostMapping(value = "/UserAddInfoApi")
@ApiOperation(value = "添加",notes = "没啥留言的")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName",required = true,paramType = "query",dataType = "String",value = "用户名"),
@ApiImplicitParam(name = "pwd",required = true,paramType = "query",dataType = "String",value = "密码"),
@ApiImplicitParam(name = "nickName",required = true,paramType = "query",dataType = "String",value = "昵称")
})
public Object UserAddInfoApi(String userName,String pwd,String nickName){
HashMap<String,Object> map=new HashMap<String,Object>();
if(
StringUtils.isEmpty(userName)||
StringUtils.isEmpty(pwd)||
StringUtils.isEmpty(nickName)
){
map.put("state",false);
map.put("msg","参数不润许为空");
map.put("result","");
return map;
}
usersService.UsersAddInfo(userName, pwd, nickName);
map.put("state",true);
map.put("msg","成功");
map.put("result","");
return map;
}
/**
* 单个查询
* @param id
* @return
*/
@GetMapping("/UsersSelectById")
@ApiOperation(value = "id查询",notes = "没啥留言的")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",required = true,paramType = "query",dataType = "String",value = "编号")
})
public Object UsersSelectById(String id){
Users users = usersService.UsersSelectById(Integer.parseInt(id));
HashMap<String,Object> map=new HashMap<String,Object>();
map.put("state",true);
map.put("msg","成功");
map.put("result",users);
return map;
}
/**
* 修改api
* @param id
* @param pwd
* @return
*/
@PostMapping(value = "/UserUpdateInfoApi")
@ApiOperation(value = "添加",notes = "没啥留言的")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",required = true,paramType = "query",dataType = "String",value = "编号"),
@ApiImplicitParam(name = "pwd",required = true,paramType = "query",dataType = "String",value = "密码"),
})
public Object UserUpdateInfoApi(String id,String pwd){
usersService.UsersUpdateInfo(pwd,Integer.parseInt(id));
HashMap<String,Object> map=new HashMap<String,Object>();
map.put("state",true);
map.put("msg","成功");
map.put("result","");
return map;
}
/**
* 删除api
* @param id
* @return
*/
@GetMapping(value = "/UsersDeleteById")
@ApiOperation(value = "根据id删除",notes = "没啥留言的")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",required = true,paramType = "query",dataType = "String",value = "编号")
})
public Object UsersDeleteById(String id){
usersService.UsersDeleteById(Integer.parseInt(id));
HashMap<String,Object> map=new HashMap<String,Object>();
map.put("state",true);
map.put("msg","成功");
map.put("result","");
return map;
}
}4、swagger的常用注解
- @Api：用于标识一个类为 Swagger 文档的资源。 用法示例：@Api(value = "User API", = "User Management")
- @ApiOperation：用于描述一个方法的操作信息。 用法示例：@ApiOperation(value = "Get user by ID", notes = "Returns a user based on ID")
- @ApiParam：用于描述一个方法参数的信息。 用法示例：@ApiParam(value = "User ID", required = true) @PathVariable("id") Long id
- @ApiModel：用于描述一个数据模型（DTO）的信息。 用法示例：@ApiModel(value = "User", description = "User details")
- @ApiModelProperty：用于描述一个属性或字段的信息。 用法示例：@ApiModelProperty(value = "User name")
- @ApiResponses：用于描述一个方法的多个响应。 用法示例：@ApiResponses(value = { @ApiResponse(code = 200, message = "Success"), @ApiResponse(code = 404, message = "Not Found") })
- @ApiIgnore：用于指定某个方法或类不在 Swagger 文档中显示。 用法示例：@ApiIgnore
5、访问效果
网页的路径是【http://127.0.0.1:8088/MyAPI/swagger-ui.html】 ，拼接方法是【ip:port/path/swagger-ui.html】
这里的path是在配置文件中的服务路径【server.servlet.context-path=/MyAPI】
总结
swagger是比较常用的一种API交流插件，JAVA和.NET都用，且大多数程序员都会使用，方便大家交流API。
