swagger注解详解

@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隐藏该属性

离线接口文档自动生成器

适用范围：

将标准的swagger.json文件解析并转换成穗大改一仿芦定格式的接口文档，其中文档的章节排序可以在index.adoc中自定义排序。生成的接口文档有html和pdf格式两种，由于插件转换中文需要特殊配置，默认生成的含中文的文档存在一定字体错乱，所以建议使用html格式文档猜判。Html格式文档可以使用word打开，并转换成其他格式。

*** 作步骤：

1.      [endif]将ConvertSwagger.rar解压出来

2.      [endif][可选步骤]修改\ConvertSwagger\src\docs\asciidoc文件夹下面的index.adoc与manual_content.adoc,manual_content.adoc。index.adoc中可以将manual_content.adoc添加进去：

并在manual_content.adoc中添加自定义描述内容：

（可选）

3.      [endif]在\ConvertSwagger\target\swagger中添加swagger.json文件

4.      [endif]编译此工程 在ConvertSwagger目录中 mvn package

5.      [endif]在\ConvertSwagger\target\asciidoc\html中拿到html格式的接口文档，自动生成的文档名称默认是index.html。

可以发现只是存在了一个URLEncoding的设置，猜测原因可能是因为存在中文路径的问题。在把SwaggerConfig中的

接口声明中的最后一个参数修改成英文后，即使不加URLEncoding的设置也可以正常访问，所以可以确定就是中文路径引起的问题族模型。在查询接口的时候，swagger的请求路径如下图：

如果group参数存在中文，而没有设置URLEncoding，那就会无法解析。

可以发现只是存在了兆猜一个URLEncoding的设置，猜测原因码空可能是因为存在中文路径的问题。在把SwaggerConfig中的

接口声明中的最后一个参数修改成英文后，即使不加URLEncoding的设置也可以正常访问，所以可以确定就是中文路径引起的问题。在查询接口的时候，swagger的请求路径如下图：

如果group参数存在中文，而没有设置URLEncoding，那就会无法解析。

---