springboot结合swagger自动生成接口文档

客官°小女子只卖身不卖艺 2022-05-23 07:53 402阅读 0赞

[springboot结合swagger自动生成接口文档][springboot_swagger]

前后台分离的开发渐渐已成趋势。那么前后端的沟通就成了问题，包括移动端，web端。如果有一个东西在我们写完代码的时候，自动将接口的所有注释，调用文档提供出来，是不是一件很美好的事情。那就是使用swagger.

1.使用swagger,首先在pom中引入jar依赖。

![复制代码][copycode.gif]

<dependency>
               <groupId>io.springfox</groupId>
               <artifactId>springfox-swagger2</artifactId>
               <version>2.2.2</version>
            </dependency>
            <dependency>
               <groupId>io.springfox</groupId>
               <artifactId>springfox-swagger-ui</artifactId>
               <version>2.2.2</version>
            </dependency>

![复制代码][copycode.gif]

2.Application.java中引入@EnableSwagger2来启动swagger注解

@Configuration
    @SpringBootApplication // 组件扫描
    @EnableScheduling
    @EnableAsync
    @EnableSwagger2
    public class Application {

3.使用接口注解

![复制代码][copycode.gif]

@RestController
    @RequestMapping("/user")
    @Api("userController相关api")
    public class UserController {
    
        @Autowired
        private UserService userService;
        
    //    @Autowired
    //    private MyRedisTemplate myRedisTemplate;
    
        @ApiOperation("获取用户信息")
        @ApiImplicitParams({
            @ApiImplicitParam(paramType="header",name="username",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"),
            @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="用户的密码",defaultValue="wangna")
        })
        @ApiResponses({
            @ApiResponse(code=400,message="请求参数没填好"),
            @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
        })
        @RequestMapping(value="/getUser",method=RequestMethod.GET)
        public User getUser(@RequestHeader("username") String username, @RequestParam("password") String password) {
            return userService.getUser(username,password);
        }
        
    //    @RequestMapping("/testJedisCluster")
    //    public User testJedisCluster(@RequestParam("username") String username){
    //        String value =  myRedisTemplate.get(MyConstants.USER_FORWARD_CACHE_PREFIX, username);
    //        if(StringUtils.isBlank(value)){
    //            myRedisTemplate.set(MyConstants.USER_FORWARD_CACHE_PREFIX, username, JSON.toJSONString(getUser()));
    //            return null;
    //        }
    //        return JSON.parseObject(value, User.class);
    //    }
        
    }

![复制代码][copycode.gif]

说明：

*  @Api：用在类上，说明该类的作用
 *  @ApiOperation：用在方法上，说明方法的作用
 *  @ApiImplicitParams：用在方法上包含一组参数说明
 *  @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    
     *  paramType：参数放在哪个地方
        
         *  header-->请求参数的获取：@RequestHeader
         *  query-->请求参数的获取：@RequestParam
         *  path（用于restful接口）-->请求参数的获取：@PathVariable
         *  body（不常用）
         *  form（不常用）
     *  name：参数名
     *  dataType：参数类型
     *  required：参数是否必须传
     *  value：参数的意思
     *  defaultValue：参数的默认值
 *  @ApiResponses：用于表示一组响应
 *  @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    
     *  code：数字，例如400
     *  message：信息，例如"请求参数没填好"
     *  response：抛出异常的类
 *  @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    
     *  @ApiModelProperty：描述一个model的属性

4.启动服务，浏览器输入"http://localhost:8080/swagger-ui.html"

![1022444-20170824164412808-1943415857.png][]

[springboot_swagger]: https://www.cnblogs.com/xu-lei/p/7423883.html
[copycode.gif]: /images/20220523/303191797737475f9671913255d780aa.png
[1022444-20170824164412808-1943415857.png]: /images/20220523/40a3b8d0c35a4ee88444555d112b9ccc.png