Swagger 了解

系统管理员 2022-05-23 01:00 190阅读 0赞

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

参考  
[Swagger简介][Swagger]  
[Swagger使用][Swagger 1]

## 简介 ##

Swagger™ 的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

### 查看 Swagger 接口 ###

项目启动后，查看 Swagger 接口，可以访问：[http://localhost:8081/swagger-ui.html][http_localhost_8081_swagger-ui.html]  
swagger-ui.html 是在 springfox-swagger-ui-2.7.0.jar 包中文件。

## 注解 ##

### Tags ###

@Api(value = “/v1/users”,tags = “Users”,description = “用户接口V1”)  
tags由Api注解的tags标签设置，如果不设置，则以类名作为 tag  
如接口类名 UserInfoService.java  
不设置tags时，user-info-service : User Info Service

### @ApiOperation ###

@ApiOperation(value="获取用户列表", notes="获取所有用户列表",produces = "application/json")  
    @RequestMapping(value="/users", method= RequestMethod.GET)
    public List<User> getUserList() {  
    List<User> r = new ArrayList<User>(users.values());
        return r;
    }

### @ApiResponses ###

@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息",produces = "application/json")
    // ApiResponses 增加返回结果的描述
    @ApiResponses(value = {@ApiResponse(code = 405,message = "Invalid input",response = Integer.class)}) (1)
    @ApiImplicitParam(name = "id",value = "用户ID",dataType = "int",paramType = "path")  (2)
    @RequestMapping(value="/users/{id}", method= RequestMethod.GET)
    public User getUser(@PathVariable Integer id) {
        return users.get(id);
    }

(1) 在默认Response的基础上增加新的Response说明  
(2) 使用ApiImplicitParam描述接口参数

### @ApiImplicitParams ###

@ApiOperation(value="更新用户名称", notes="更新指定用户的名称")
    @RequestMapping(value="/users/{id}", method= RequestMethod.POST)
    @ApiImplicitParams({  （1）
            @ApiImplicitParam(name = "id",value = "用户ID",paramType = "path",dataType = "int"),  (2)
            @ApiImplicitParam(name = "userName",value = "用户名称",paramType = "form",dataType = "string")
    })
    public void updateUserName(@PathVariable Integer id,@RequestParam String userName){
        User u = users.get(id);
        u.setName(userName);
    }

(1) 使用ApiImplicitParams描述多个参数  
(2) 使用ApiImplicitParam时，需要指定paramType,这样也便于swagger ui 生成参数的输入格式。

paramType 有五个可选值 ： path, query, body, header, form

### @ApiParam ###

@ApiOperation(value="创建用户-传递简单对象", notes="传递简单对象",produces = "application/json")
    @RequestMapping(value="/users-1", method= RequestMethod.POST)
    //可以不加ApiParam注解，需要给参数添加描述时可以使用这个注解，或者使用ApiImplicitParams注解 (1)
    public Map postUser(@RequestParam  String userName,@ApiParam("地址") @RequestParam(required = false) String address) { 
        User user = new User();
        user.setId(Math.round(10));
        user.setName(userName);
        user.setAddress(address);
        users.put(user.getId(), user);
        return ImmutableMap.of("user",user);
    }

(1) 使用ApiParam描述接口参数

ApiImplicitParam 与 ApiParam 的区别

*  对Servlets或者非 JAX-RS的环境，只能使用 ApiImplicitParam。
 *  在使用上，ApiImplicitParam比ApiParam具有更少的代码侵入性，只要写在方法上就可以了，但是需要提供具体的属性才能配合swagger ui解析使用。
 *  ApiParam只需要较少的属性，与swagger ui配合更好。

### @ModelAttribute ###

传递复杂对象用。

@ApiOperation(value="创建用户-传递复杂对象", notes="传递复杂对象DTO, url参数拼接",produces = "application/json")
    @RequestMapping(value="/users-2", method= RequestMethod.POST)
    //传递对象推荐使用ModelAttribute注解
    public Map postUser2(@ModelAttribute User user) {  (1)
        users.put(user.getId(),user);
        return ImmutableMap.of("user",user);
    }

(1) ModelAttribute 是Spring mvc的注解，这里Swagger可以解析这个注解，获得User的属性描述

### @RequestBody ###

@ApiOperation(value="创建用户-传递复杂对象", notes="传递复杂对象DTO，json格式传递数据",produces = "application/json")
    @RequestMapping(value="/users-3", method= RequestMethod.POST)
    //json格式传递对象使用RequestBody注解
    public User postUser3(@RequestBody User user) {
        users.put(user.getId(),user);
        return user;
    }

### @ApiModel ###

@ApiModel(value = "User", description = "用户对象")
    public class User {
    
        @ApiModelProperty(value = "ID")
        private Integer id;
        @ApiModelProperty(value = "姓名")
        private String name;
        @ApiModelProperty(value = "地址")
        private String address;
        @ApiModelProperty(value = "年龄",access = "hidden")
        private int age;
        @ApiModelProperty(value = "性别")
        private int sex;
        .......
    }

### @PathVariable ###

@ApiOperation(value="删除用户- PathVariable", notes="根据url的id来指定删除对象")
    @RequestMapping(value="/users/{id}", method = RequestMethod.DELETE)
    public void deleteUser(@PathVariable Integer id) {  (1)
        users.remove(id);
    }

(1) PathVariable是Spring 的注解，对于这种简单的参数，就可以不用写ApiParam来描述接口参数。

### 数组的描述 ###

@ApiOperation(value="删除用户-传递数组", notes="删除对象，传递数组")
    @RequestMapping(value="/users/deleteByIds", method = RequestMethod.DELETE)
    public void deleteUser(@ApiParam("用户ID数组") @RequestParam Integer[] ids) {  (1)
        for (int id:ids){
            users.remove(id);
        }
    }

(1) 这里用ApiParam为数组参数添加描述

[Swagger]: https://blog.csdn.net/wangnan9279/article/details/44541665
[Swagger 1]: https://www.cnblogs.com/softidea/p/6251249.html
[http_localhost_8081_swagger-ui.html]: http://localhost:8081/swagger-ui.html