spring boot restful api documentation with swagger 2

举报
Amrf 发表于 2018/12/12 16:42:29 2018/12/12
【摘要】 https://springframework.guru/spring-boot-restful-api-documentation-with-swagger-2/ https://dzone.com/articles/spring-boot-restful-api-documentation-with-swagger https://blog.csdn.net/boonya/article...

https://springframework.guru/spring-boot-restful-api-documentation-with-swagger-2/

https://dzone.com/articles/spring-boot-restful-api-documentation-with-swagger

https://blog.csdn.net/boonya/article/details/60875405

Spring Boot使开发RESTful服务变得非常容易 - 并且使用Swagger可以轻松地记录RESTful服务。

构建后端API层引入了一个全新的领域,超越了仅仅实现端点的挑战。 您现在有客户端,现在将使用您的API。 您的客户需要知道如何与您的API进行互动。 在基于SOAP的Web服务中,您有一个WSDL可以使用。 这为API开发人员提供了一个基于XML的合同,它定义了API。 但是,对于RESTFul Web服务,没有WSDL。 因此,您的API文档变得更加重要。

API文档应该结构化,使其具有信息性,简洁性和易于阅读。 但是最佳实践,如何记录你的API,它的结构,什么包括和什么不是是一个不同的主题,我不会在这里覆盖。 有关文档的最佳实践,我建议由Andy Wikinson进行此演示。

在本文中,我将介绍如何使用Swagger 2为Spring Boot项目生成REST API文档。

https://blog.csdn.net/yangshijin1988/article/details/69937309

https://blog.csdn.net/top_code/article/details/54023136

https://blog.csdn.net/SIMBA1949/article/details/80919183

https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md


Swagger 2框架是一种可视化Api接口文档,用过rap的同事应该了解,跟阿里的rap功能比较相似。Swagger 2框架可以生成在线的Api文档,然后每个接口的输入、输出、返回一目了然,还可以在线上输入接口的参数,进行自测,方便前后端一起联调,非常方便。而且Spring boot中引入Swagger 2框架非常简单。

Swagger注解

Swagger的注解都是接口描述类的,主要作用就是描述接口的文档,其有以下注解。

- @Api()用于类;

表示标识这个类是swagger的资源

- @ApiOperation()用于方法;

表示一个http请求的操作

- @ApiParam()用于方法,参数,字段说明;

表示对参数的添加元数据(说明或是否必填等)

- @ApiModel()用于类

表示对类进行说明,用于参数用实体类接收

- @ApiModelProperty()用于方法,字段

表示对model属性的说明或者数据操作更改

- @ApiIgnore()用于类,方法,方法参数

表示这个方法或者类被忽略

- @ApiImplicitParam() 用于方法

表示单独的请求参数

- @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam


【版权声明】本文为华为云社区用户转载文章,如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。