本文是配置swagger的文章，版本是【2.9.2】
1、pom.xml的jar包引入
这里为了后文操作方便，我多添加了一个commons-lang3的包用于字符串的非空判断。
<!-- 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】
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注解写法
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。
