swagger入门

优点

  • 可调试
  • 容易编写
  • swagger 驱动api开发

开发流程

  • swagger-editor:http://editor.swagger.io/ 或静态服务
  • 生成user.yaml,如下面的示例,并放在静太服务器上
  • swagger-ui:下载并放在静态服务上
  • swagger-ui加上user.yaml

文档

示例

swagger: '2.0'
info:
  title: My Demo API
  description: 举个栗子,关于用户注册登录
  version: 1.0.0
  contact: 
    name: 王东文
    email: wangdongwen@meicai.cn
    url: http://www.meicai.cn
host: api.uber.com
schemes:
  - https
  - http
basePath: /v1
consumes:
  - application/x-www-form-urlencoded
produces:
  - application/json
paths:
  /user/login:
    get:
      summary: 用户登录
      description: |
        用户登录模块
      parameters:
        - name: username
          in: formData
          description: 用户名
          required: true
          type: string
          format: phone
        - name: password
          in: formData
          description: 密码
          required: true
          type: string
          format: password
      tags:
        - User
      responses:
        '200':
          description: 登录成功
          schema:
            $ref: '#/definitions/LoginOk'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  LoginOk:
    type: object
    properties:
      token:
        type: string
        description: 登录成功后,产生的访问token
      message:
        type: string
        description: 登录成功提示
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
        description: 错误码
      message:
        type: string
        description: 错误信息描述
发布了90 篇原创文章 · 获赞 8 · 访问量 16万+
展开阅读全文

springboot中form-data传值,不用@Requestbody修饰入参对象时,swagger-ui该怎么聚合它的属性

08-20

**1、环境描述**:在springboot+swagger v_2.9.2的环境下 前后端分离,restful风格接口。 **2、提问原因**:前后端约定使用form-data进行数据传递,后台接口入参很多都是: public String findPage(String pageNo, String pageSize, Batch entity)这样的, **调试好swagger接口文档后发现**:如果将参数Batch用@Requestbody修饰,接口文档中的参数parameter就是聚合显示,如果后台没有使用@Requestbody修饰,那么swagger将递归该参数对象Batch的所有属性,包括其中的Page<Batch>,具体如下图: (![两种接收参数方式对swagger-ui的影响](https://img-ask.csdn.net/upload/201908/20/1566316583_639624.png) **图片描述**:(不知道图片看的清不) 同一个接口,仅仅只是入参对象的修饰语不同,在swagger上居然区别这么大 左边的swagger上看起来是正常的,网络上很多人都是用这种@Requestbody方式,但是我们约定的是form-data,所以不能使用@Requestbody接收参数。而如果不用,那么swagger文档上看到的都是全部铺开的,不是很方便使用。 **3、我尝试过的方法** 1.我想过两个方向,一个是修改后台swagger处理数据的拼装逻辑,另一个方向是在页面端修改数据的位置和逻辑,也就是修改api-doc接口返回的数据, **==第一个方向**:修改后台swagger处理数据的拼装结构,借鉴了(https://blog.csdn.net/u010579482/article/details/79990536) 中的一个思路,重写子类覆盖swagger主要处理参数数据的ModelAttributeParameterExpander,到目前为止还没有解决。 **==第二个方向**:修改页面端api-doc接口返回的数据,根据图上两种方式的对比,我们可以发现: **被@Requestbody修饰的入参对象**,在swagger-ui的definitions中已经有了一个对象的定义或声明: ![被@Requestbody修饰](https://img-ask.csdn.net/upload/201908/20/1566306781_529537.png) ![图片说明](https://img-ask.csdn.net/upload/201908/20/1566306934_308277.png) **而没有被@Requestbody修饰的返回结果**,在swagger-ui里返回结果就直接是在path.post.parameters中平铺在一起,也就是不方便所在,如果入参对象里有子对象,那递归出来就是一大片了。如下图: ![图片说明](https://img-ask.csdn.net/upload/201908/20/1566308568_957422.png) **4、现状:**到目前为止,还没有解决这个问题,各位大佬有时间的话教育下小弟,小弟在线等着,还望大佬们不吝赐教,[感激][感激][感激] 问答

没有更多推荐了,返回首页

©️2019 CSDN 皮肤主题: 大白 设计师: CSDN官方博客

分享到微信朋友圈

×

扫一扫,手机浏览