会员登录 立即注册

搜索

[CATIA V5教程下载] Springboot入门之-配置swagger文档

[复制链接]
kudoathrun 发表于 2018-9-11 21:09:03 | 显示全部楼层 |阅读模式
kudoathrun
2018-9-11 21:09:03 935 3 看全部
Springboot入门之-配置swagger文档18



Swagger是什么?

Swagger 是一款目前世界最流行的API管理工具。但目前Swagger已经形成一个生态圈,能够管理API的整个生命周期,从设计、文档到测试与部署。Swagger有几个重要特性:

  • 代码侵入式注解
  • 遵循YAML文档格式
  • 非常适合三端(PC、iOS及Android)的API管理,尤其适合前后端完全分离的架构模式。
  • 减少没有必要的文档,符合敏捷开发理念
  • 功能强大
Swagger拥有众多不同语言和平台的开源实现与工具,主要有:

  • Swagger UI,基于Swagger-compliant API的一套可以展示优美文档的Web应用。
  • Swagger Editor,一款以YAML格式编辑与管理API的工具,同时支持JSON格式的文档描述。
  • Swagger-Core,Swagger的Java/Scala实现,并已集成 JAX-RS (Jersey, Resteasy, CXF...), Servlets与Play Framework。
  • Swagger-JS,Swagger的Javascript版本实现。
尤其要注意的是Swagger UI,它是Swagger的Web页面展现形式,能够对符合swagger规范的文件进行解析与显示。通过友好的页面,可以对API进行分组管理、文档显示以及实现mock测试。所以在大多数情形下,都使用Swagger UI实现对API的管理与展现。
Maven依赖pom.xml
io.springfox springfox-swagger2 2.6.1 io.springfox springfox-swagger-ui 2.6.1Swagger配置

@Configurationpublic class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.tongcao.cn.contoller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("springboot利用swagger构建api文档") .description("简单优雅的restfun风格,http://blog.csdn.net/saytime") .termsOfServiceUrl("http://blog.csdn.net/saytime") .version("1.0") .build(); }}


注:记得在Application 加Swagger注解

Springboot入门之-配置swagger文档8



Swagger注解说明
常用到的注解有:


  • Api
  • ApiModel
  • ApiModelProperty
  • ApiOperation
  • ApiParam
  • ApiResponse
  • ApiResponses
  • ResponseHeader
1. api标记

Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式:
@Api(value = "/user", description = "Operations about user")@Api

  • 该注解将一个Controller(Class)标注为一个swagger资源(API)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。该注解包含以下几个重要属性:
  • tags
  • API分组标签。具有相同标签的API将会被归并在一组内展示。
  • value
  • 如果tags没有定义,value将作为Api的tags使用
  • description
  • API的详细描述,在1.5.X版本之后不再使用,但实际发现在2.0.0版本中仍然可以使用
Springboot入门之-配置swagger文档5



@ApiOperation

  • 在指定的(路由)路径上,对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有:
  • value
  • 对操作的简单说明,长度为120个字母,60个汉字。
  • notes
  • 对操作的详细说明。
  • httpMethod
  • HTTP请求的动作名,可选值有:"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
  • code
  • 默认为200,有效值必须符合标准的HTTP Status Code Definitions。
Springboot入门之-配置swagger文档2




  • @ApiImplicitParams
  • 注解ApiImplicitParam的容器类,以数组方式存储。
  • @ApiImplicitParam
  • 对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定,但这个@ApiImplicitParam注解可以以统一的方式定义参数列表,也是在Servelet及非JAX-RS环境下,唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性:
  • name
  • 参数名称
  • value
  • 参数的简短描述
  • required
  • 是否为必传参数
  • dataType
  • 参数类型,可以为类名,也可以为基本类型(String,int、boolean等)
  • paramType
  • 参数的传入(请求)类型,可选的值有path, query, body, header or form。
  • @ApiParam
  • 增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有:
  • required
  • 是否为必传参数
  • value
  • 参数简短说明
  • @ApiResponses
  • 注解@ApiResponse的包装类,数组结构。即使需要使用一个@ApiResponse注解,也需要将@ApiResponse注解包含在注解@ApiResponses内。
  • @ApiResponse
  • 描述一个操作可能的返回结果。当REST API请求发生时,这个注解可用于描述所有可能的成功与错误码。可以用,也可以不用这个注解去描述操作的返回类型,但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型,那么需要分别定义返回值,并将返回类型进行关联。但Swagger不支持同一返回码,多种返回类型的注解。注意:这个注解必须被包含在@ApiResponses注解中。
  • code
  • HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
  • message
  • 更加易于理解的文本消息
  • response
  • 返回类型信息,必须使用完全限定类名,比如“com.xyz.cc.Person.class”。
  • responseContainer
  • 如果返回类型为容器类型,可以设置相应的值。有效值为 "List", "Set" or "Map",其他任何无效的值都会被忽略。
Model的注解
对于Model的注解,Swagger提供了两个:@ApiModel及@ApiModelProperty,分别用以描述Model及Model内的属性。

  • @ApiModel
  • 提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内,所有的类将自动被内省(introspected),但利用这个注解可以做一些更加详细的model结构说明。主要属性有:
  • value
  • model的别名,默认为类名
  • description
  • model的详细描述
  • @ApiModelProperty
  • 对model属性的注解,主要的属性值有:
  • value
  • 属性简短描述
  • example
  • 属性的示例值
  • required
  • 是否为必须值
启动项目后默认访问路径:
http://localhost:8080/swagger-ui.html
tuofama 发表于 2018-9-13 22:48:28 | 显示全部楼层
tuofama
2018-9-13 22:48:28 看全部
楼主是我最佩服的人!
winit 发表于 2018-9-17 14:53:14 | 显示全部楼层
winit
2018-9-17 14:53:14 看全部
为自己的想法加分点赞
c302079 发表于 2018-9-29 03:28:44 | 显示全部楼层
c302079
2018-9-29 03:28:44 看全部
楼主是最棒的
  • 您可能感兴趣
您需要登录后才可以回帖 登录 | 立即注册 |  

本版积分规则 返回列表

查看:935 | 回复:3

catia版本| plm之家论坛| cad新手论坛| catia v6论坛| 汽车catia论坛| 中国catia论坛| catia绘图练习| CATIA论坛
联系电话:18602879577 地址:成都市青羊区二环路西一段155号天祥广场4栋1801 邮箱:wanqiang@rydit.com.cn ICP备案号: ( 蜀ICP备14018086号 )
Copyright © 2001-2013 Comsenz Inc. All Rights Reserved.   Powered by Discuz! X3.4
快速回复 返回顶部 返回列表