详解Swagger接口文档和常用注解的使用

目录
  • 一、Spring整合Swagger
  • 二、swagger常用注解说明
    • 1、@Api的使用说明
    • 2、@ApiOperation的使用说明
    • 3、@ApiParam的使用说明
    • 4、@ApiModel的使用说明
    • 5、@ApiModelProperty的使用说明
    • 6、@ApiIgnore的使用说明
    • 7、@ApiImplicitParam的使用说明
    • 8、@ApiImplicitParams的使用说明
    • 9、@ApiResponses与@ApiResponse使用说明
    • 10、@RequestMapping注解的推荐配置

Swagger是一款遵循 Restful 风格的接口文档开发神器,支持基于 API 自动生成接口文档,接口文档始终与 API 保持同步,不再需要手动编写接口文档,并且采用全注解的方式,开发简单,代码侵入性低,对服务端开发的程序员来说非常方便,可以节约大量写接口文档的时间。除此之外,Swagger 生成的文档还支持在线测试,参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。

一、Spring整合Swagger

(1)在 pom.xml 文件中添加 Swagger 的 maven 依赖:

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

(2)编写Swagger自定义配置类:

/**
* 类说明 :自定义swagger配置信息
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
     public Docket creatApi(){
     return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select() //选择哪些路径和api会生成document
      .apis(RequestHandlerSelectors.basePackage("com.zwp.controller"))//controller路径
      //.apis(RequestHandlerSelectors.any())   //对所有api进行监控
      .paths(PathSelectors.any())  //对所有路径进行监控
      .build();
     }

    //接口文档的一些基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springmvc+swagger整合")//文档主标题
                .description("test接口文档")//文档描述
                .version("1.0.0")//API的版本
                .termsOfServiceUrl("###")
                .license("LICENSE")
                .licenseUrl("###")
                .build();
    }
}

在 springmvc.xml 文件中配置创建对象:

<!-- 使用注解驱动:自动配置处理器映射器与处理器适配器 -->
<mvc:annotation-driven />
<!-- 注解方式:自动扫描该包 -->
<context:component-scan base-package="com.zwp.config" />

(3)在 springmvc.xml 中过滤掉 swagger-ui 的静态资源文件:

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

(4)在controller类添加swagger的注解:

//在类上面加@Api注解,表明该controller类需要被swagger自动生成文档
@Api(tags="UserController",description="user的控制层")
@Controller
@RequestMapping("/user")
public class UserController {

    @Autowired
    private UserService userService;

     //在方法上面添加@ApiOperation注解,表明该方法需要被swagger自动生成文档
    @ApiOperation(httpMethod="GET",value="接口标题:获取用户信息",notes="接口的notes说明:需要user的id")
    @RequestMapping(value="/getUserById/{userId}",method=RequestMethod.GET)
    public @ResponseBody User getUserById(@PathVariable Integer userId){
        return userService.getUserById(userId);
    }

}

(5)部署工程,访问路径:

格式:http://服务器ip:端口/项目名称//swagger-ui.html

例子:http://localhost:8080/ssm/swagger-ui.html

见到上面页面,表示整合成功。

二、swagger常用注解说明

注解 说明
@Api 修饰controller类,标识这个类是swagger的资源 
@ApiOperation 修饰controller的方法,表示一个http请求的操作
@ApiParam 修饰方法的参数,用于添加参数说明与是否必填等元数据
@ApiModel 修饰对象类,表示对对象类进行说明,用于参数用实体类接收的场景
@ApiModelProperty 修饰对象类中的属性,对属性进行说明
@ApiIgnore() 修饰类、方法、参数等,表示不显示在swagger文档中
@ApiImplicitParam 用于方法,表示单独的请求参数
@ApiImplicitParams 用于方法,包含多个 @ApiImplicitParam

1、@Api的使用说明

修饰controller类,标识这个类是swagger的资源,属性说明:

tags:类的说明,但是tags如果有多个值,会生成多个list

value:也是类的说明,可以使用tags替代

@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {

}

效果图:

2、@ApiOperation的使用说明

修饰controller的方法,表示一个http请求的操作,属性说明:

value:用于方法描述

notes:用于提示内容

tags:可以重新分组,视情况而用)

3、@ApiParam的使用说明

修饰方法的参数,用于添加参数说明与是否必填等元数据,属性说明:

name:参数名

value:参数说明

required:是否必填

@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
     @ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")
     @GetMapping("/getUserInfo")
     public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
     // userService可忽略,是业务逻辑
      User user = userService.getUserInfo();

      return user;
  }
}

效果图:

4、@ApiModel的使用说明

修饰对象类,表示对对象类进行说明,用于参数用实体类接收的场景,属性说明:

value:表示对象名,可省略

description:描述,可省略

5、@ApiModelProperty的使用说明

修饰对象类中的属性,对属性进行说明,属性说明:

  • value:字段说明
  • name:重写属性名字
  • dataType:重写属性类型
  • required:是否必填
  • example:举例说明
  • hidden:是否隐藏
@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="用户名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;

      @ApiModelProperty(value="id数组",hidden=true)
      private String[] ids;
      private List<String> idList;
}
  @ApiOperation("更改用户信息")
  @PostMapping("/updateUserInfo")
  public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){

     int num = userService.updateUserInfo(user);
     return num;
  }

效果图:

6、@ApiIgnore的使用说明

修饰类、方法、参数等,表示不显示在swagger文档中,比较简单, 这里不做举例

7、@ApiImplicitParam的使用说明

用于方法,表示单独的请求参数

8、@ApiImplicitParams的使用说明

用于方法,包含多个 @ApiImplicitParam,属性说明:

  • name:参数ming
  • value:参数说明
  • dataType:数据类型
  • paramType:参数类型
  • example:举例说明
  @ApiOperation("查询测试")
  @GetMapping("select")
  //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
  @ApiImplicitParams({
  @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
  @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
  public void select(){

  }

效果图:

9、@ApiResponses与@ApiResponse使用说明

这两个注解都表示对响应结果进行说明

10、@RequestMapping注解的推荐配置

value、method、produces

示例:

    @ApiOperation("信息软删除")
    @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"),
            @ApiResponse(code = CommonStatus.EXCEPTION, message = "服务器内部异常"),
            @ApiResponse(code = CommonStatus.FORBIDDEN, message = "权限不足") })
    @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true) })
    @RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public RestfulProtocol remove(Long id) {

以上就是详解Swagger接口文档和常用注解的使用的详细内容,更多关于Swagger接口文档 注解的资料请关注我们其它相关文章!

(0)

相关推荐

  • swagger注解@ApiModelProperty失效情况的解决

    目录 swagger注解@ApiModelProperty失效 swagger 版本 2.29.2 解决方式: 小写字段名 @ApiModelProperty注解的使用 下面是它内部的常用属性 swagger注解@ApiModelProperty失效 swagger 版本 2.29.2 解决方式: 小写字段名 @ApiModelProperty注解的使用 首先要知道@ApiModelProperty是swagger的注解,它的作用是添加和操作属性模块的数据 下面是它内部的常用属性 1.value

  • springboot swagger2注解使用的教程

    swagger2 注解整体说明  最近在使用Swagger的时候忘记了注解的用法,特此记录一下. @Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置" @ApiOperation:用在请求的方法上,说明方法的用途.作用 value="说明方法的用途.作用" notes="方法的备注说明" @ApiImplicit

  • SpringBoot整合Swagger3生成接口文档过程解析

    前后端分离的项目,接口文档的存在十分重要.与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低.与新版的swagger3相比swagger2配置更少,使用更加方便. 一.pom文件中引入Swagger3依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId

  • 详解SpringBoot结合swagger2快速生成简单的接口文档

    1. pom.xml中加入依赖 <dependency> <groupId>com.spring4all</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>1.8.0.RELEASE</version> </dependency> 2. 在启动类(即带@SpringBootApplication这个注解的类)上添加@E

  • Swagger注解-@ApiModel和@ApiModelProperty的用法

    目录 @ApiModel 使用场景 概述 属性 @ApiModelProperty 使用场景 概述 属性 Swagger踩坑@ApiModel注解问题 @ApiModel 使用场景 在实体类上边使用,标记类时swagger的解析类 概述 提供有关swagger模型的其它信息,类将在操作中用作类型时自动内省 属性 属性名称 数据类型 默认值 说明 value String 类名 为模型提供备用名称 description String “” 提供详细的类描述 parent Class<?> pa

  • Spring boot集成swagger2生成接口文档的全过程

    一.Swagger介绍 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的web服务.目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器.这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件. 二.使用swagger优势 1.对于后端开发人员来说 不用再手写Wiki接口拼大量参数,避免手写错误 对代码侵入性低,采用全注解的方式,开发简单 方法参数名修改.

  • Swagger中@ApiIgnore注解的使用详解

    目录 Swagger @ApiIgnore注解的使用 1.作用在类上时,整个类都会被忽略 2.当作用在方法上时,方法将被忽略 3.作用在参数上时,单个具体的参数会被忽略 4. 在实体类中忽略不需要字段的方式 Swagger中的常用注解 1.作用在类上时,整个类都会被忽略 2.当作用在方法上时,方法将被忽略 3.作用在参数上时,单个具体的参数会被忽略 Swagger @ApiIgnore注解的使用 @ApiIgnore 可以用在类.方法上,方法参数中,用来屏蔽某些接口或参数,使其不在页面上显示.

  • Springboot整合Swagger3全注解配置(springdoc-openapi-ui)

    目录 一.创建Springboot项目,引入pom依赖 二.配置类请求头携带token 三.配置文件 四.接口定义 五.实现类 六.实体类定义 七.运行项目查看效果 一.创建Springboot项目,引入pom依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </depend

  • 详解Swagger接口文档和常用注解的使用

    目录 一.Spring整合Swagger 二.swagger常用注解说明 1.@Api的使用说明 2.@ApiOperation的使用说明 3.@ApiParam的使用说明 4.@ApiModel的使用说明 5.@ApiModelProperty的使用说明 6.@ApiIgnore的使用说明 7.@ApiImplicitParam的使用说明 8.@ApiImplicitParams的使用说明 9.@ApiResponses与@ApiResponse使用说明 10.@RequestMapping注

  • SpringBoot使用swagger生成api接口文档的方法详解

    目录 前言 具体例子 maven配置 项目application.yml配置 springApplication添加swagger注解 在控制层添加swagger注解 前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot系列文章: spring boot项目使用mybatis-plus代码生成实例 具体例子 maven配置 在使用之前,我们需要添加s

  • go swagger生成接口文档使用教程

    目录 前言 Swagger介绍 1.安装 2.检测是否安装成功 3.安装gin-swagger扩展 使用 1.添加注释 2.生成接口文档数据 3.引入gin-swagger渲染文档数据 总结 前言 这篇文章主要介绍了Go语言使用swagger生成接口文档的方法,希望能够对大家的学习或工作具有一定的帮助,需要的朋友可以参考下. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率.那如何维护接口文档,历来都是令人头痛的,感觉很浪费精力

  • java集成开发SpringBoot生成接口文档示例实现

    目录 为什么要用Swagger ? Swagger集成 第一步: 引入依赖包 第二步:修改配置文件 第三步,配置API接口 Unable to infer base url For input string: "" Swagger美化 第一步: 引入依赖包 第二步:启用knife4j增强 Swagger参数分组 分组使用说明 1.在bean对象的属性里配置如下注释 2.在接口参数的时候加入组规则校验 小结 大家好,我是飘渺. SpringBoot老鸟系列的文章已经写了两篇,每篇的阅读反

  • Flask实现swagger在线文档与接口测试流程详解

    目录 1.什么是restful 2.swagger/openAPI能做什么 3.python如何实现swagger 4.flasgger的使用案例 5.完整代码 阅读对象:知道什么是restful,有了解swagger或者openAPI更佳. 1.什么是restful Representional State Transfer(REST):表征状态转移.是一种一种基于HTTP协议的架构.采用Web 服务使用标准的 HTTP 方法 (GET/PUT/POST/DELETE) 将所有 Web 系统的

  • spring boot集成smart-doc自动生成接口文档详解

    目录 前言 功能特性 1 项目中创建 /src/main/resources/smart-doc.json配置文件 2 配置内容如下(指定文档的输出路径) 3 pom.xml下添加配置 4 运行插件 5 找到存放路径浏览器打开 6 测试结果 前言 smart-doc 是一款同时支持 java restful api 和 Apache Dubbo rpc 接口文档生成的工具,smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法. smart-doc 完全基于

  • Springboot中整合knife4j接口文档的过程详解

    目录 什么是knife4j 界面欣赏 主页 接口文档 调试界面 参数实体 整合 knife4j 引入 maven 依赖 knife4j 配置文件 配置API接口 knife4j 常用特性 全局参数 离线文档 在项目开发过程中,web项目的前后端分离开发,APP开发,需要由前端后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发. 什么是knife4j 简单说knife4j就swagger的升级版API文档的一个框架,但是用起来比swagger方便多了,UI更加丰富. 界面欣赏

  • Go语言使用swagger生成接口文档的方法

    swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服务.Swagger包括自动文档,代码生成和测试用例生成. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率.可是编写接口文档历来都是令人头痛的,而且后续接口文档的维护也十分耗费精力. 最好是有一种方案能够既满足我们输出文档的需要又能

  • Spring Boot 使用 Swagger 构建 RestAPI 接口文档

    源码地址:https://github.com/laolunsi/spring-boot-examples 目前SpringBoot常被用于开发Java Web应用,特别是前后端分离项目.为方便前后端开发人员进行沟通,我们在SpringBoot引入了Swagger. Swagger作用于接口,让接口数据可视化,尤其适用于Restful APi 本节分两部分介绍,第一部分是SpringBoot引入Swagger的两种方式,第二部分是详细介绍在Web接口上应用Swagger的注解. 本篇文章使用Sp

  • 教你利用springboot集成swagger并生成接口文档

    效果图 实现步骤 1.maven中引入jar包,不同版本的swagger可能页面效果不一样. <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.1</version> </dependency> <dependency> <groupId&g

随机推荐