在使用springboot开发web项目时，用到了swagger框架，来生成web api文档。但是其中有一项是举例说明参数的结构，如下图：

但是，这个功能真的是非常方便，因为可以让前端开发人员第一时间得知参数的内部结构是什么样的，这尤其适用于那些json体结构的参数。网上的例子都是这样的：

但是，我无论如何都弄不出来这个样子，前前后后研究了有好几个小时。

终于找出了问题。

网上的api接口中，几乎全是传入一个完整的Java Bean对象，而不是传JsonObject对象。

我的代码是这样：

    @ApiOperation(value = "添加景区下的特价门票", notes = "{\"scenicIdArr\" : [53361,53356]}")
    @PostMapping(value = "/special_price/add")
    public JSONObject addSpecialPrice(@RequestBody JSONObject scenicIdArr) {
        return sprSvc.addSpecialPrice(scenicIdArr);
别人的代码是这样：
    @ApiOperation("更改用户信息")
    @PostMapping("/updateUserInfo")
    public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){
        int num = userService.updateUserInfo(user);
        return num;
经过比较，很容易就发现了问题，我的接口中的参数是无法得知内部数据结构的JSONObject类型，而别人的参数是一个已知其内部数据结构的User对象。
既然知道了原因，那我也将接口进行了一些修改：
创建一个符合我业务要求的数据结构实体类，然后将这个实体类作为参数传入接口中：
    @ApiOperation(value = "添加景区下的特价门票", notes = "{\"scenicIdArr\" : [53361,53356]}")
    @PostMapping(value = "/special_price/add")
    public JSONObject addSpecialPrice(@RequestBody ScenicIdArr scenicIdArr) {
        return null;
    @ApiModel
    class ScenicIdArr {
        @ApiModelProperty(value = "景区id数组")
        int[] scenicIdArr;
上述代码中，我定义了一个成员内部类，并将实体类以@ApiModel进行注解。效果如下：
呵呵，没有一丁点效果！我陷入了沉思... ...
于是我大胆的猜想：swagger框架可能是自动调用了get或set方法，并完成页面渲染。
于是我又修改了代码：
@ApiOperation(value = "添加景区下的特价门票", notes = "{\"scenicIdArr\" : [53361,53356]}")
    @PostMapping(value = "/special_price/add")
    public JSONObject addSpecialPrice(@RequestBody ScenicIdArr scenicIdArr) {
        return null;
    @ApiModel
    class ScenicIdArr {
        @ApiModelProperty(value = "景区id数组")
        int[] scenicIdArr;
        public int[] getScenicIdArr() {
            return scenicIdArr;
我加了一个get方法，来获取实体类中的属性，看一下效果：
上图中可以看到，不论是整体的实体类结构，还是字段上的注释“景区id数组”都很好的显示了出来。这样，我们在页面点击小黄框的时候，就可以将数据自动的加载到参数填写的白框内。
这样，我们省去了手动书写结构和key值的过程，而只需要我们输入具体的value值即可。
由于本篇博客并不是教你如何使用spring-boot-starter-swagger自动依赖配置模块中的各种注解如何使用，因此，此处只是简单解析了一下接口参数的模板生成方式。
但是，题目中既然提到了这个功能的缺陷，就不得不回过头来吐槽一下这个破JB玩意儿！
这个在小黄框显示对外接口参数结构的功能真的应该说是非常实用的一个功能，我并不知道这个功能具体的名称是什么，暂且就称它为“参数样例功能”。
为什么说这个功能非常实用？
首先，书写简便。REST接口风格的参数多以json结构体传输数据，而这样一个自动生成结构体的功能，可以为我们免去书写大量括号、冒号、逗号、引号、空格等json体的必须元素，而且自动排版，避免手写出错，达到零错误。在真正通过页面的api接口测试的时候，只需要简单输入几个value值就可以“try it out”了，着实提高了不少效率。
其次，方便前端开发。我们都知道，不论是传入JavaBean对象，还是传入没有在后端强制类型约束的Json字符串，前端调用controller中的接口时，仅仅是传入一个key-value的结构，才不会管你什么JavaBean。对于springboot，其一系列内嵌的HttpMessageConverter会将json结构转化成对应的JavaBean，再交给Controller。前端开发人员甚至可以将小黄框内的内容，直接拷贝过来，稍作修改（value赋值）即可完成对后端接口对接的全部编码。
第三，覆盖了其他部分注解。个人认为，swagger中的注解关于参数注释方面，有些重复，这一点不做展开讨论，且仅仅是个人观点，可以参考官方api文档体会一下。另外关于response一类的注解，完全没有必要。返回值是什么结构的，完全可以通过“try it out”调用一次接口即可了解到。估计swagger开发团队考虑到功能的完整性，或者在后端由于某种原因导致接口不可用而做的一种补足方案（比如，数据库中暂无数据等原因）。
虽然这个功能实用，但是依然存在一个很别扭的情况。
那就是，我们不得不因为要在“参数样例功能”中展示我们的参数结构而创建一个Java Bean。不论这个Java Bean在后台逻辑中有无实际意义。
就比方说我之前的那个接口：
    @ApiOperation(value = "添加景区下的特价门票", notes = "{\"scenicIdArr\" : [53361,53356]}")
    @PostMapping(value = "/special_price/add")
    public JSONObject addSpecialPrice(@RequestBody JSONObject scenicIdArr)
我需要拿到一个有景区id组成的json体的数据结构，然后跑到service中去处理，可能我的这种api结构并不规范，但是不可能不存在这样一种情况：仅仅规定一个json结构，而不是Java Bean来作为参数进行处理。（抱歉，最近在看《Thinking In Java》句子写起来有那么一点模仿布鲁斯埃克尔的腔调）
我查找了很多资料，包括官方的API说明，并没有很好解决方案。于是，才有了后面的成员内部类的出现。但是这种代码除了方便测试以外完全没有实际意义。如果为每个以json结构体作为参数的接口另起一个class文件去明确传入参数的结构，就显得有些愚蠢。它会使你的代码非常的臃肿和凌乱。
这就是我说的swagger的这个缺陷，以纯json结构体作为参数的接口，无法实现非常重要的“参数样例功能”。
综上，就是我对swagger框架的一点看法和总结，如有疑问，欢迎文末留言。
                    问题描述在使用springboot开发web项目时，用到了swagger框架，来生成web api文档。但是其中有一项是举例说明参数的结构，如下图：但是，这个功能真的是非常方便，因为可以让前端开发人员第一时间得知参数的内部结构是什么样的，这尤其适用于那些json体结构的参数。网上的例子都是这样的：但是，我无论如何都弄不出来这个样子，前前后后研究了有好几个小时。终于找出了问题。问题原因网上的api接...
原因很简单，因为接口入参中含有nodeName（即使用VO封装了也不行）
而nodeName是html dom的关键字，swagger无法接收这样的字段，也就无法执行接口
其实这应该看作是swagger的bug，因为接口实际上是没有问题的，只要不用swagger，还是可以正常访问执行
如果必须要用nodeName这个参数，又想用swagger，那么就在VO上用注解@RequestBody吧
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency&gt
				
在swagger上生成关于json数据类型返回结果的描述
注解ApiReturnJsonObject表示返回结果的map结构
package com.test.swagger2;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.Re...
　Swagger 是一个规范和完整的框架，用于生成、描述、调用以及可视化的 Restful 风格的 Web 服务。
　　简单的理解：是一款 REST API 文档生成工具，生成在线的接口文档，方便接口测试。
2.为什么使用swagger
    前后端分离开发时，为了方便前后端接口调用规范，需要提供一个接口文档，但是维护这个接口文档是一个及其繁琐的事情，可能一不小心就忘记更新该文档从而导致前后端接口调用失败。
　　Swagger 就是为了解决这个问题而出现的（在线接...
				
Swagger API 接口文档生成工具的利与弊
作为Java后台工程师其中的一员，作者深知众多的开发者没有写接口文档的习惯。尤其是一些新手，他们只想着把功能实现、和前端开发者把接口调试通就好了，没有考虑到后期的项目维护。当他们接受一个旧项目，进行二次开发的时候，突然发现看别人的代码太难了，既没有注释，也没有接口文档，看懂一块代码逻辑要大半天，时间都浪费在了读懂旧代码上了。
为了能够偷懒(不写接口文档)，开发者发明了一种神器— Swagger ...
				
Swagger总结
Swagger是一个可以帮你自动生成接口文档的工具，并且可以在线对接口进行测试。当然想要让Swagger自动帮你生成接口文档，你需要在项目中使用到Swagger的几个常用注解：
@Api :加在Controller类上面，说明这个Controller的作用
@ApiOperation：加在Controller类里面的每个方法上，说明这个方法的作用
@ApiImplicitParams：加在Controller类的方法上，用来说明一组请求参数的含义
@ApiImplicitPar
				
文章目录一、接口展示中的问题二、BaseResult工具类三、使用BaseResult1. 对应一个url该怎么返回数据2. swagger中的数据展示四、多层嵌套1. 嵌入一层列表2. 返回分页信息3. 对象里有另外的对象五、总结
一、接口展示中的问题
  现在大部分前后端的数据交互都是采用json格式，如我们经常用一个大的json包裹着数据发送的，但是在Swagger中，如果直接返回这个类对象...
上文中我们介绍了如果给Controller中的参数添加字段说明：https://blog.csdn.net/shangcunshanfu/article/details/100838687，也留下了一个问题，那就是如何给JSONObject类型的参数添加字段说明，本章就来进行介绍
Swagger其实是没有针对JSONObject添加字段说明功能的，这也很好理解，因为Swagger并没...
				
Swagger是一个用于描述、生成和调试Web API的工具。它使用一种名为OpenAPI的标准来定义API的描述文档，这种标准也称为Swagger标准。
要使用Swagger，您需要以下几步：
1. 在您的Web API项目中添加Swagger包。 在.NET Core中，可以使用NuGet包管理器添加Microsoft.AspNetCore.Swagger包。
2. 在Startup.cs文件的ConfigureServices方法中添加Swagger服务。
public void ConfigureServices(IServiceCollection services)
    // Add Swagger services to the services container.
    services.AddSwaggerGen();
3. 在Startup.cs文件的Configure方法中使用Swagger中间件。
public void Configure(IApplicationBuilder app)
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();
    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
4. 使用注释来描述您的API操作。 您可以使用XML文档注释或Swashbuckle.AspNetCore.Annotations包中的注释来完成此操作。
5. 在Startup.cs文件的ConfigureServices方法中配置Swagger文档。
public void ConfigureServices(IServiceCollection services)
    // Add Swagger services to the services container.
    services.AddSwaggerGen(c =>
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
6. 启动Web API并访问/swagger路径，您将看到Swagger UI。 在Swagger UI中，您可以查看和测试您的API操作。
这就是使用Swagger的基本步骤。有关更多信息，