Swagger Annotations

本文详细介绍了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);
    }
效果:




评论 2
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值