2025年swagger2注解（swagger2注解使用）

大家好，我是讯享网，很高兴认识大家。
                <p id="0A24HOKU"><strong>SpringBoot 2.1.4与Swagger2的集成生成RESTful接口文档</strong></p><p id="0A24HOKV">来源：http://www.bj9420.com</p><p id="0A24HOL0">编者： wRitchie（吴理琪）  </p><p id="0A24HOL1">Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful风格的Web服务。总体目标是使客户端的接口文档与服务端接口同步更新，当我们在后台的接口修改了后，Swagger可以实现自动的更新，而不需要人为的维护这个接口进行测试。接口文档的方法，参数和模型紧密集成到服务器端的代码，允许API始终保持同步。</p><p><h5>第一步：pom.xml添加依赖，引入jar包：</h5></p><p id="0A24HOL2">Swagger版本声明</p><p><blockquote id="0A24HOM5"><br/>2.9.2<br/></blockquote></p><p id="0A24HOL4">版本依赖:</p><p><blockquote id="0A24HOM6"><br/>   io.springfox<br/>   springfox-swagger-ui<br/>   ${swagger2.version}<br/>   io.springfox<br/>   springfox-swagger2<br/>   ${swagger2.version}<br/></blockquote><h5>第二步：Swagger的配置启动类编写：</h5></p><p id="0A24HOL6">使用Swagger需进行一些配置，编写配置启动类Swagger2.java，配置相关信息将在Swagger接口首页上显示，类似于接口说明书，在Swagger2类中使用注解来进行启动Swagger，注意，在SpringBoot的启动类如SmApplication.java同级创建Swagger2.java</p><p class="f_center"><img src="https://nimg.ws.126.net/?url=http%3A%2F%2Fdingyue.ws.126.net%2F2021%2F0929%2F5f129512j00r06psg000kc000bd00akc.png&thumbnail=660x2147483647&quality=80&type=jpg"/><br/></p><p id="0A24HOL8">Swagger2.java具体配置如下:</p><p><blockquote id="0A24HOM7">package com.bj9420;<br/>import org.springframework.beans.factory.annotation.Value;<br/>import org.springframework.context.annotation.Bean;<br/>import org.springframework.context.annotation.Configuration;<br/>import springfox.documentation.builders.ApiInfoBuilder;<br/>import springfox.documentation.builders.PathSelectors;<br/>import springfox.documentation.builders.RequestHandlerSelectors;<br/>import springfox.documentation.service.ApiInfo;<br/>import springfox.documentation.service.Contact;<br/>import springfox.documentation.spi.DocumentationType;<br/>import springfox.documentation.spring.web.plugins.Docket;<br/>import springfox.documentation.swagger2.annotations.EnableSwagger2;<br/>/<br/>* @Title: Swagger2.java<br/>* @Description: Swagger2的配置文件  http://IP:端口/swagger-ui.html<br/>* http://localhost:8081/swagger-ui.html<br/>* @author: wRitchie  <br/>* @date: 2019/1/4 15:07<br/>* @version: V1.0<br/>* @Copyright (c): 2019 http://bj9420.com   All rights reserved.<br/>*/<br/>@Configuration<br/>@EnableSwagger2<br/>public class Swagger2 {<br/>   @Value("${swagger2.enable}")<br/>   private boolean enable;<br/>   /swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等*/<br/>   @Bean<br/>   public Docket createRestApi() {<br/>       return new Docket(DocumentationType.SWAGGER_2)<br/>               .apiInfo(apiInfo())<br/>               .select()<br/>               //为当前包路径<br/>               .apis(RequestHandlerSelectors.basePackage("com.bj9420.controller"))<br/>               .paths(PathSelectors.any())<br/>               .build().enable(enable);<br/>   }<br/>   /构建 api文档的详细信息函数,注意这里的注解引用的是哪个*/<br/>   private ApiInfo apiInfo() {<br/>       return new ApiInfoBuilder()<br/>               //页面标题<br/>               .title("SM项目RESTful API文档")<br/>               //创建人<br/>               .contact(new Contact("wRitchie", "http://www.bj9420.com", "408873941@.com"))<br/>               //版本号<br/>               .version("1.0.0")<br/>               //描述<br/>               .description("SM项目接口文档，本项目所有文档终以在线的形式提供，如有疑问，请及时有我们联系，本文档将实时更新，确保最新版的接口可用。")<br/>               .build();<br/>   }<br/>}<br/></blockquote></p><p id="0A24HOLA">其中： .apis(RequestHandlerSelectors.basePackage("com.bj9420.controller"))指定了以扫描包的方式进行，会把com.bj9420.controller包下的controller都扫描到。</p><p><h5>第三步：使用Swagger来进行模拟测试，主要是在controller层，实例如下：</h5><blockquote id="0A24HOM8">package com.bj9420.controller.user;<br/>import com.bj9420.framework.SystemConstant;<br/>import com.bj9420.framework.util.AESUtil;<br/>import com.bj9420.framework.util.MD5Util;<br/>import com.bj9420.framework.util.StringUtil;<br/>import com.bj9420.model.Result;<br/>import com.bj9420.model.User;<br/>import com.bj9420.service.user.IUserService;<br/>import io.swagger.annotations.*;<br/>import org.slf4j.Logger;<br/>import org.slf4j.LoggerFactory;<br/>import org.springframework.beans.factory.annotation.Autowired;<br/>import org.springframework.web.bind.annotation.*;<br/>import java.util.HashMap;<br/>import java.util.List;<br/>import java.util.Map;<br/>/<br/>* @Title: UserController.java<br/>* @Description: 用户控制类，使用Swagger2提供接口文档范本<br/>* @author: wRitchie  <br/>* @date: 2019/1/4 15:14<br/>* @version: V1.0<br/>* @Copyright (c): 2019 http://bj9420.com   All rights reserved.<br/>*/<br/>@Api(value = "用户控制类", tags = "用户控制类")<br/>@RestController<br/>@RequestMapping("/user")<br/>public class UserController {<br/>   @Autowired<br/>   private IUserService userService;<br/>   private static final Logger log = LoggerFactory.getLogger(UserController.class);<br/>   /注意：paramType需要指定为path,不然不能正常获取*/<br/>   @ApiOperation(value = "查询用户信息", notes = "根据用户标识查询用户信息")<br/>   @ApiImplicitParam(name = "userId", value = "用户标识", paramType = "path", dataType = "Integer")<br/>   @RequestMapping(value = "/{userId}", method = RequestMethod.GET)<br/>   public User getUser(@PathVariable Integer userId) {<br/>       log.info("开始查询某个用户信息");<br/>       return userService.selectByPrimaryKey(userId);<br/>   }<br/>   /注意：paramType需要指定为body*/<br/>   @ApiOperation(value = "新建用户", notes = "新建一个用户")<br/>   @ApiImplicitParams({@ApiImplicitParam(name = "user", value = "用户数据", required = true, paramType = "body", dataType = "User") })<br/>   //@RequestMapping(value = "", method = RequestMethod.POST)<br/>   @PostMapping("")<br/>   public Result addUser(@ApiParam(value = "用户数据", required = true) @RequestBody User user) {<br/>       /模拟客户端app生成的md5密码，实现后台用户与app用户密码的一致性*/<br/>       String pwdTmp=MD5Util.encode(user.getPassword());<br/>       String sKey = MD5Util.md5(SystemConstant.SYSTEM_SKEY).substring(0, 16);<br/>       String pwdEncrypt = AESUtil.encrypt(pwdTmp, sKey).substring(0, 16);<br/>       user.setPassword(pwdEncrypt);<br/>       int returnValue = userService.insert(user);<br/>       if (returnValue &gt; 0) {<br/>           return Result.success("新建用户成功。",user);<br/>       }else{<br/>           return Result.failure("新建用户失败。",null);<br/>       }<br/>   }<br/>   @ApiOperation(value = "获取用户列表", notes = "分页查询获取用户列表信息")<br/>   @ApiImplicitParams({@ApiImplicitParam(name = "map",value = "用户数据Map形式",dataType = "Map")})<br/>   @GetMapping("")<br/>   public Map  listByPager(@RequestParam  Map map) {<br/>       Map jsonMap = new HashMap();<br/>       /* 分页处理 /<br/>       //draw : 表示请求次数<br/>       String draw=map.get("draw")+"";<br/>       //start :第一条数据的起始位置，比如0代表第一条数据<br/>       String start=map.get("start")+"";<br/>       //length:告诉服务器每页显示的条数<br/>       String length=map.get("length")+"";<br/>       //排序字段名称<br/>       String sortname=map.get("sortname")+"";<br/>       //排序升降<br/>       String sortorder=map.get("sortorder")+"";<br/>       //是否分页标记<br/>       String pager=map.get("pager")+"";<br/>       if (StringUtil.isEmpty(draw)) {<br/>           draw = "0";<br/>       }<br/>       if(StringUtil.isEmpty(start)) {<br/>           start="0";<br/>       }<br/>       if (StringUtil.isEmpty(length)) {<br/>           length = SystemConstant.PAGER_SIZE;<br/>       }<br/>       if (StringUtil.isEmpty(pager)) {<br/>           pager = null;<br/>       }<br/>       map.put("start", start);<br/>       map.put("len", length);<br/>       // 排序<br/>       String orderbyStr=null;<br/>       if(!StringUtil.isEmpty(sortname)){<br/>           if("createTime".equals(sortname)){<br/>               orderbyStr="order by  create_time "+sortorder;<br/>           }else if("modifyTime".equals(sortname)){<br/>               orderbyStr="order by  modify_time "+sortorder;<br/>           }else if("userId".equals(sortname)){<br/>               orderbyStr="order by user_id "+sortorder;<br/>           }else if("loginName".equals(sortname)){<br/>               orderbyStr="order by login_name "+sortorder;<br/>           }else if("realName".equals(sortname)){<br/>               orderbyStr="order by real_name "+sortorder;<br/>           }else if("sex".equals(sortname)){<br/>               orderbyStr="order by sex "+sortorder;<br/>           }else if("orgName".equals(sortname)){<br/>               orderbyStr="order by org_id "+sortorder;<br/>           }else if("phoneNumber".equals(sortname)){<br/>               orderbyStr="order by phone_number "+sortorder;<br/>           }else if ("userStatus".equals(sortname)) {<br/>               orderbyStr = "order by userStatus " + sortorder;<br/>           }<br/>       }else{<br/>           orderbyStr="order by user_id desc";<br/>       }<br/>       map.put("pager", pager);<br/>       map.put("orderBy", orderbyStr);<br/>       List list = userService.selectByPager(map);<br/>       int allSize =userService.selectByPagerCount(map);<br/>       jsonMap.put("draw", draw);<br/>       jsonMap.put("start", start);<br/>       jsonMap.put("length", length);<br/>       jsonMap.put("sortorder", sortorder);<br/>       jsonMap.put("sortname", sortname);<br/>       jsonMap.put("pager", pager);<br/>       //具体的数据对象数组<br/>       jsonMap.put("data", list);<br/>       // 总记录数<br/>       jsonMap.put("recordsTotal", allSize);<br/>       return jsonMap;<br/>   }<br/>   @ApiOperation(value = "删除用户", notes = "根据用户ID删除用户")<br/>   @ApiImplicitParam(name = "userId", value = "用户标识", paramType = "path", dataType = "Integer")<br/>   @RequestMapping(value = "/{userId}", method = RequestMethod.DELETE)<br/>   public String delUser(@PathVariable int userId) {<br/>       int returnValue = userService.deleteByPrimaryKey(userId);<br/>       if (returnValue &gt; 0) {<br/>           return "删除成功。";<br/>       }<br/>       return "删除失败。";<br/>   }<br/>   @ApiOperation(value = "更新用户", notes = "更新已存在用户")<br/>   @ApiImplicitParam(name = "user", value = "用户数据", required = true, paramType = "body", dataType = "User")<br/>   @RequestMapping(value = "", method = RequestMethod.PUT)<br/>   public Result update(@RequestBody User user) {<br/>       int returnValue = userService.updateByPrimaryKeySelective(user);<br/>       if (returnValue &gt; 0) {<br/>           return Result.success("更新用户成功。",user);<br/>       }else{<br/>           return Result.failure("更新户失败。",null);<br/>       }<br/>   }<br/>}<br/></blockquote></p><p id="0A24HOLC">Swagger2相关注解介绍</p><p id="0A24HOLD">1. @Api：用在类上，说明该类的作用</p><p id="0A24HOLE">2. @ApiOperation：用在方法上，说明方法的作用</p><p id="0A24HOLF">3. @ApiImplicitParams：用在方法上包含一组参数说明</p><p id="0A24HOLG">4. @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面</p><p id="0A24HOLH">paramType：参数放在哪个地方</p><p id="0A24HOLI">· header --&gt; 请求参数的获取：@RequestHeader</p><p id="0A24HOLJ">· query --&gt;请求参数的获取：@RequestParam</p><p id="0A24HOLK">· path（用于restful接口）--&gt; 请求参数的获取：@PathVariable</p><p id="0A24HOLL">· body（不常用）</p><p id="0A24HOLM">· form（不常用）</p><p id="0A24HOLN">name：参数名</p><p id="0A24HOLO">dataType：参数类型</p><p id="0A24HOLP">required：参数是否必须传</p><p id="0A24HOLQ">value：参数的意思</p><p id="0A24HOLR">defaultValue：参数的默认值</p><p id="0A24HOLS">5. @ApiResponses：用于表示一组响应</p><p id="0A24HOLT">6. @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息</p><p id="0A24HOLU">code：数字，例如400</p><p id="0A24HOLV">message：信息，例如"请求参数没填好"</p><p id="0A24HOM0">response：抛出异常的类</p><p id="0A24HOM1">7. @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）</p><p id="0A24HOM2">8. @ApiModelProperty：描述一个model的属性</p><p><h5>第四步：启动应用，浏览器访问：http://localhost:8081/swagger-ui.html，正常展示 api 接口文档界面，如下：</h5></p><p class="f_center"><img src="https://nimg.ws.126.net/?url=http%3A%2F%2Fdingyue.ws.126.net%2F2021%2F0929%2F5df12893j00r06psh004hc001gz00qsc.png&thumbnail=660x2147483647&quality=80&type=jpg"/><br/></p><p><h5>第五步，实际应用，选择相应的接口，点击Try it out按钮，输入相关参数，点击Execute，即可看到返回结果，如下图所示：</h5></p><p class="f_center"><img src="https://nimg.ws.126.net/?url=http%3A%2F%2Fdingyue.ws.126.net%2F2021%2F0929%2F4722b26fj00r06psj002tc0013x00r0c.png&thumbnail=660x2147483647&quality=80&type=jpg"/><br/></p><p><h5>结论：这样很方便，不用像postman一样来编写入口，Swagger2自动完成，而且实时更新。至此Swagger2与SpringBoot集成完毕。</h5></p>
讯享网
2025年swagger2注解（swagger2注解使用）

相关推荐
