Swagger Annotations

最新推荐文章于 2023-12-22 17:05:15 发布

原创最新推荐文章于 2023-12-22 17:05:15 发布 · 1.9w 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#swagger #annotation

SOA/RESTful 专栏收录该内容

2 篇文章

订阅专栏

本文详细介绍了Swagger注解的使用方法，包括@Api、@ApiOperation、@ApiParam等，并提供了具体的代码示例，帮助开发者更好地理解如何利用这些注解来生成API文档。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

以下是swagger-anntations-1.5.9.jar中的所有类（注解）

Api.class

ApiImplicitParam.class
ApiImplicitParams.class
ApiModel.class
ApiModelProperty.class
ApiOperation.class
ApiParam.class
ApiResponse.class
ApiResponses.class
Authorization.class
AuthorizationScope.class
Contact.class
Example.class
ExampleProperty.class
Extension.class
ExtensionProperty.class
ExternalDocs.class
Info.class
License.class
ResponseHeader.class
SwaggerDefinition.class

Tag.class

@Api 标记一个类为Swagger资源（开放的API）通过description来描述其功能。如：@Api(value = "restful", description = "关于Restful接口文档注释")

@ApiOperation 描述HTTP 方法类型对应的一个操作 CRUD,value和notes来描述其功能如：@ApiOperation(value = "GET获取数据",produces="application/json")

@ApiParam 描述请求参数 @ApiParam(name = "id", value = "编号", required = true)

@ApiImplicitParams (@ApiImplicitParam) 与@ApiParm功能相同都是对请求参数的注释

最后结果：

@ApiParam 注释请求参数，自动探测参数类型、参数对应类型path、query、heaer、body等信息

@ApiParam遇到POST请求消息体 JSON封装的数据，SpringMVC使用User等实体类接收时

@ApiOperation(value = "POST BODY更新数据")
    @RequestMapping(value = "resources/{id}", method = RequestMethod.POST)
    public ResponseEntity<ModelMap> bodyResource(@ApiParam(value="用户",required=true) @RequestBody User user, 
            @ApiParam(name = "id", value = "编号", required = true) @PathVariable String id){
        System.out.println(user);
        ModelMap modelMap = new ModelMap();
        modelMap.put("status", HttpStatus.OK.value());
        modelMap.put("timestamps",System.currentTimeMillis());
        modelMap.put("msg", HttpStatus.OK.getReasonPhrase());
        modelMap.put("user", user);
        modelMap.put("apiversion", 2);
        return ResponseEntity.status(HttpStatus.OK).body(modelMap);
    }

User实体类：

/**
* ClassName : User.java
* Create on ：2017年1月19日
* Copyrights 2017 guanfl All rights reserved.
* Email : guanfl@foxmail.com
*/
package com.github.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户描述")
public class User {
    @ApiModelProperty(value="用户名称",required=true)
    private String name;
    @ApiModelProperty(value="用户年龄",required=true)
    private Integer age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    @Override
    public String toString() {
        return "User [name=" + name + ", age=" + age + "]";
    }
}

效果：

@ApiParam 请求参数使用@ModelAttribute 接收参数并转换成实体对象

@ApiOperation(value = "GET BODY更新数据")
    @RequestMapping(value = "model/{id}", method = RequestMethod.GET)
    public ResponseEntity<ModelMap> modelResource(@ApiParam(value="用户",required=true) @ModelAttribute User user, 
            @ApiParam(name = "id", value = "编号", required = true) @PathVariable String id){
        System.out.println(user);
        ModelMap modelMap = new ModelMap();
        modelMap.put("status", HttpStatus.OK.value());
        modelMap.put("timestamps",System.currentTimeMillis());
        modelMap.put("msg", HttpStatus.OK.getReasonPhrase());
        modelMap.put("user", user);
        modelMap.put("apiversion", 2);
        return ResponseEntity.status(HttpStatus.OK).body(modelMap);
    }

效果：