spring boot restful api documentation with swagger 2

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