swagger api文档

• 在团队开发中，一个好的 API 文档不但可以减少大量的沟通成本，还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节，并在程序员之间代代相传。

• Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：

  • 1.接口文档在线自动生成，文档随接口变动实时更新，节省维护成本

  • 2.支持在线接口测试，不依赖第三方工具

• Swagger 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型：

参考链接写的非常详细

参考链接写的非常详细：https://blog.csdn.net/HiBoyljw/article/details/81110553

自己整理：

@Api：

修饰整个类，描述Controller的作用

@ApiOperation：

描述一个类的一个方法，或者说一个接口
@@PostMapping("/app/{user_id}/")
@ApiOperation(value = “创建topic”,notes = “创建topic”,response = KafkaTopicBean.class)

@ApiParam：

单个参数描述

@@PostMapping("/app/{user_id}/")
    public Map<String,String> createUser(@ApiParam(value = "用户id")                                                           

@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiRespons和@RequestMapping

• @ApiRespons：HTTP响应其中1个描述

@ApiResponse(code = 201,message = "创建用户成功")

• @@ResponseStatus ：http请求的返回状态码

@ResponseStatus(code = HttpStatus.CREATED)

code 和 value一个意思，.这里@ResponseStatus作用就是改变服务器响应的状态码 ,比如一个本是200的请求可以通过@ResponseStatus 改成201/500等等.

常见的几个状态码 HttpStatus.OK 就是 200 , HttpStatus.INTERNAL_SERVER_ERROR 就是 500 等等 ，具体的查看 HttpStatus枚举 有详细说明.
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表