swagger-ui及swagger用法

默认的swagger-ui好用但是不够美观，为了让生成的文档更加可观，我们可以使用swagger-ui-layer 来美化。

swagger-ui-layer，基于layui 开源的swagger-ui的替换。界面大气，使用起来也很方便。swagger-ui-layer 依于swagger的功能，所以在原先项目中导入以下依赖即可

注意：

使用规则：

一、在返回对象类上中要使用注解@ApiModel(value="实体类对象", description="实体类描述")，对象字段上使用@ApiModelProperty(value=”字段说明“,required=”是否必填”)表示对model属性的说明

注意：@ApiModel value 不能同名，否则会导致参数乱窜.

二、@API使用在Controller类上，表明是swagger资源

@Api(value = "仓库管理controller", tags = {"仓库管理接口"})

三、在每个接口方法中使用注解@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”)；表示一个http请求的 *** 作

四、 @RequestBody和@ApiImplicitParam不能共用

@RequestBody主要用来接收前端传递给后端的json字符串中的数据的，如果想要swagger显示出实体类的参数描述信息要在实体类上使用@ApiModel(value="")

原先：在接口方法中会使用@ApiImplicitParam(name = "vo", value = "用户实体类", paramType = "body", required = true, dataType = "UserVo") 但@RequestBody和@ApiImplicitParam注解，会使实体类参数描述信息显示不出来，所以@ApiImplicitParam适用于没有接收实体类参数的方法

五、 @ApiParam 用于 Controller 中方法的参数说明。如图所示。

六、如果接口中，实体参数的描述没有显示出来可以加上@ModelAttribute 注解

七、通过 @PathVariable 可以将 URL 中占位符参数绑定到控制器处理方法的入参中：URL 中的 {xxx} 占位符可以通过@PathVariable(“xxx“) 绑定到 *** 作方法的入参中。在swagger接口文档中，不会显示出这个占位符的具体信息，如下不会显示出这个id的说明

建议使用@ApiParam注解：

也可以使用@ApiImplicitParam对接收的参数进行解释

注意：

要改成这样

八、在使用@RequestParam注解，获得前台传递的值，一般要结合@ApiParam注解使用

@Api：用在类上，说明类的作用

    tags：“标签，可以在UI界面上看到的注解”

    value：url的路径值，在类上使用的路由，如果类上没有配置，此注解无效

    position：如果配置多个Api 想改变显示的顺序位置

    protocols：协议

    hidden：配置为true 将在文档中隐藏

    produces：返回的文件的MIME类型，例如application/json,application/xml

    consumes：需要的文件的MIME类型，

    authorizations：认证

@ApiSort：排序

    value：int值

@ApiOperation：用在方法上，用来给API增加方法说明。

    value=“说明方法的用途、作用”

    notes=“方法的备注说明”

    tags：如果设置这个值、value的值会被覆盖

    description：对api资源的描述

    basePath

    position

    protocols

    hidden

    response：返回的对象，例如（Bean.class）

    responseContainer：返回的内容，有效的 “List”, “Set” or “Map”.，其他无效

    httpMethod：

    code ：默认为200

    extensions：扩展属性

    produces：返回的文件的MIME类型，例如application/json,application/xml

    consumes：需要的文件的MIME类型，

    ignoreJsonView:忽略的json

@ApiImplicitParam：用来注解来给方法入参增加说明。

    paramType:参数存在的位置，该参数不能乱写，否者测试时会调用失败

        header：请求参数放置于Request Header，使用@RequestHeader获取

        query：请求参数放置于请求地址，使用@RequestParam获取

        path：（用于restful接口）–>请求参数的获取：@PathVariable

        body：@RequestBody

        form：表单提交

    name：参数名

    dataType：参数类型

    required：参数是否必须传（bool类型）

    value：说明参数的意思

    defaultValue：参数的默认值

    allowableValues：允许的值

    allowMultiple：是否允许多选

    allowEmptyValue：允许为空？

    readOnly：只读？

**@ApiImplicitParams **: 用在方法上包含一组参数说明。

    ApiImplicitParam[] value()：包含ApiImplicitParam

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

    code：数字，例如400

    message：信息，例如"请求参数没填好"

    response：响应类

@ResponseHeader：响应头设置

    name:响应名称

    description:描述信息

    response:响应类

    responseContainer:响应内容

@ApiModel：一般用在实体类，描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候

    @ApiModelProperty：描述一个model的属性

ApiParam ：使用在参数上（和ApiImplicitParam使用其一即可）

name属性名称

value属性值

defaultValue默认属性值

allowableValues可以不配置

required是否属性必填

access

allowMultiple默认为false

hidden隐藏该属性

直接在Controller类上添加注解，常用的注解如下：

@Api 配置方法API

@ApiOperation API的 *** 作 GET PUT DELETE POST

@ApiParam API的方法参数描述

---