一个简单的 OpenAPI3.0 实例，使用 SpringBoot 和 Prism 测试

avatar 2018年07月16日14:38:12 6 10374 views
博主分享免费Java教学视频，B站账号：Java刘哥 ，长期提供技术问题解决、项目定制：本站商品点此
Swagger 在线编辑器：http://editor.swagger.io/

一、API 代码

  1. openapi: 3.0.0
  2. info:
  3.   description: <p>Springboot 整合swagger demo，使用swagger2构建restful api . <p>
  4.   version: 1.0.1
  5.   title: 'Swagger editor demo '
  6.   contact:
  7.     name: 联系开发人员
  8.     email: 847064370@qq.com
  9. servers:
  10.   - url: 'http://{domain}:{port}/{basePath}'
  11.     description: http请求
  12.     variables:
  13.       domain:
  14.         default: localhost
  15.         description: HTTP API请求域名
  16.       port:
  17.         enum:
  18.           - '8080'
  19.           - '8081'
  20.         default: '8080'
  21.       basePath:
  22.         default: ''
  23.   - url: 'https://{domain}:{port}/{basePath}'
  24.     description: https请求
  25.     variables:
  26.       domain:
  27.         default: localhost
  28.         description: HTTPs API请求域名
  29.       port:
  30.         enum:
  31.           - '8080'
  32.           - '8081'
  33.         default: '8080'
  34.       basePath:
  35.         default: ''
  36. tags:
  37.   - name: user
  38.     description: 用户相关操作
  39. components:
  40.   schemas:
  41.     ErrorCode:
  42.       type: integer
  43.       format: int64
  44.       enum:
  45.         - 0
  46.         - 10001
  47.         - 10002
  48.       description: |
  49.         用户请求返回的信息码
  50.           * 0：请求成功
  51.           * 10001：用户名不存在
  52.           * 10002：用户密码错误
  53.           * 10003：内部错误
  55.     ResultMessage:
  56.       type: object
  57.       properties:
  58.         code:
  59.           $ref: '#/components/schemas/ErrorCode'
  60.         message:
  61.           description: 错误信息描述
  62.           type: string
  63.         data:
  64.           type: object
  65.           description: 请求返回的内容（JSON类型）
  66.     User:
  67.       type: object
  68.       properties:
  69.         id:
  70.           description: 主键ID
  71.           type: string
  72.           format: uuid
  73.         username:
  74.           description: 用户登录名
  75.           type: string
  76.         password:
  77.           description: 密码
  78.           type: string
  79. paths:
  80.   /user:
  81.     post:
  82.       tags:
  83.         - user
  84.       summary: add user
  85.       description: 新增用户信息
  86.       operationId: addUser
  87.       requestBody:
  88.         content:
  89.           application/json:
  90.             schema:
  91.               $ref: '#/components/schemas/User'
  92.       responses:
  93.         default:
  94.           description: 请求成功后返回的内容
  95.           content:
  96.             application/json:
  97.               schema:
  98.                 type: object
  99.                 properties:
  100.                   code:
  101.                     $ref: '#/components/schemas/ErrorCode'
  102.                   message:
  103.                     description: 错误信息描述
  104.                     type: string
  105.                   data:
  106.                     type: object
  107.                     description: 请求返回的内容（JSON类型）
  108.                 example:
  109.                   code: 0
  110.                   message: 请求成功
  111.                   data:
  112.                     id: 创建的用户的主键ID
  113.     get:
  114.       tags:
  115.         - user
  116.       summary: 批量获取用户信息
  117.       responses:
  118.         default:
  119.           description: 请求成功后返回的内容
  120.           content:
  121.             application/json:
  122.               schema:
  123.                 type: array
  124.                 items:
  125.                   $ref: '#/components/schemas/User'
  126.   '/user/{userId}':
  127.     get:
  128.       tags:
  129.         - user
  130.       summary: find user by id
  131.       description: 根据ID获取用户信息
  132.       operationId: findUserById
  133.       parameters:
  134.         - name: userId
  135.           in: path
  136.           description: 用ID
  137.           required: true
  138.           schema:
  139.             type: string
  140.       responses:
  141.         '400':
  142.           description: 请求失败
  143.         default:
  144.           description: 请求成功后返回的内容
  145.           content:
  146.             application/json:
  147.               schema:
  148.                 type: object
  149.                 properties:
  150.                   code:
  151.                     $ref: '#/components/schemas/ErrorCode'
  152.                   message:
  153.                     description: 错误信息描述
  154.                     type: string
  155.                   data:
  156.                     type: object
  157.                     description: 请求返回的内容（JSON类型）
  158.                 example:
  159.                   code: 0
  160.                   message: 操作成功
  161.                   data:
  162.                     user:
  163.                       id: uuid
  164.                       username: 用户登录名
  165.                       password: 用户密码
  166.     put:
  167.       tags:
  168.         - user
  169.       summary: update user
  170.       description: 修改用户信息
  171.       operationId: updateUser
  172.       parameters:
  173.         - name: userId
  174.           in: path
  175.           description: 用ID
  176.           required: true
  177.           schema:
  178.             type: integer
  179.       requestBody:
  180.         content:
  181.           application/json:
  182.             schema:
  183.               $ref: '#/components/schemas/User'
  184.       responses:
  185.         default:
  186.           description: 操作请求成功
  187.           content:
  188.             application/json:
  189.               schema:
  190.                 type: object
  191.                 properties:
  192.                   code:
  193.                     $ref: '#/components/schemas/ErrorCode'
  194.                   message:
  195.                     description: 错误信息描述
  196.                     type: string
  197.                   data:
  198.                     type: object
  199.                     description: 请求返回的内容（JSON类型）
  200.                 example:
  201.                   code: 0
  202.                   message: 操作成功
  203.                   data:
  204.                     user:
  205.                       id: uuid
  206.                       username: 用户登录名
  207.                       password: 用户密码
  208.     delete:
  209.       tags:
  210.         - user
  211.       summary: delete user
  212.       description: 删除用户信息
  213.       operationId: deleteUser
  214.       parameters:
  215.         - name: userId
  216.           in: path
  217.           description: 用ID
  218.           required: true
  219.           schema:
  220.             type: string
  221.       responses:
  222.         default:
  223.           description: 操作请求成功
  224.           content:
  225.             application/json:
  226.               schema:
  227.                 type: object
  228.                 properties:
  229.                   code:
  230.                     $ref: '#/components/schemas/ErrorCode'
  231.                   message:
  232.                     description: 错误信息描述
  233.                     type: string
  234.                   data:
  235.                     type: object
  236.                     description: 请求返回的内容（JSON类型）
  237.                 example:
  238.                   code: 0
  239.                   message: 请求成功
  240.                   data:
  241.                     id: 删除的ID
  242. externalDocs:
  243.   url: 'https:/liuyanzhao.com'
  244.   description: '@言小曌'

在 Swagger 编辑器中粘贴上面代码，如下图




二、通过 SpringBoot 测试，验证

  1. package com.liuyanzhao.cloud.controller;
  3. import com.alibaba.fastjson.JSON;
  4. import com.liuyanzhao.cloud.entity.User;
  5. import com.liuyanzhao.cloud.repository.UserRepository;
  6. import com.liuyanzhao.cloud.vo.ResultVO;
  7. import org.springframework.beans.factory.annotation.Autowired;
  9. import org.springframework.http.ResponseEntity;
  10. import org.springframework.web.bind.annotation.*;
  12. import javax.servlet.http.HttpServletResponse;
  13. import java.util.HashMap;
  14. import java.util.List;
  16. /**
  17.  * @author 言曌
  18.  * @date 2018/7/16 10:31
  19.  */
  21. @CrossOrigin(origins = "*", allowedHeaders = "*")
  22. @RestController
  23. public class UserController {
  25.     @Autowired
  26.     private UserRepository userRepository;
  28.     /**
  29.      * 获得用户列表
  30.      *
  31.      * @return
  32.      */
  33.     @GetMapping("/user")
  34.     public List<User> getUserList() {
  35.         return userRepository.findAll();
  36.     }
  39.     /**
  40.      * 根据ID查询用户
  41.      *
  42.      * @param id
  43.      * @param response
  44.      * @return
  45.      */
  46.     @GetMapping("/user/{id}")
  47.     public ResponseEntity<ResultVO> getUser(@PathVariable("id") Integer id, HttpServletResponse response) {
  48.         User user = userRepository.findOne(id);
  49.         if (user != null) {
  50.             HashMap<String,User> map = new HashMap<>();
  51.             map.put("user",user);
  52.             return ResponseEntity.ok().body(new ResultVO(0, "操作成功", map));
  53.         } else {
  54.             response.setStatus(404);
  55.             return ResponseEntity.ok().body(new ResultVO(10001, "用户不存在"));
  56.         }
  57.     }
  59.     /**
  60.      * 添加新用户
  61.      *
  62.      * @param user
  63.      * @param response
  64.      * @return
  65.      */
  66.     @PostMapping("/user")
  67.     public ResponseEntity<ResultVO> saveUser(@RequestBody User user, HttpServletResponse response) {
  68.         User result = null;
  69.         try {
  70.             result = userRepository.save(user);
  71.         } catch (Exception e) {
  72.             response.setStatus(500);
  73.             ResponseEntity.ok().body(new ResultVO(10003, "添加失败！"));
  74.         }
  75.         HashMap<String,User> map = new HashMap<>();
  76.         map.put("user",result);
  77.         return ResponseEntity.ok().body(new ResultVO(0, "操作成功！", map));
  78.     }
  80.     /**
  81.      * 修改用户
  82.      *
  83.      * @param user
  84.      * @return
  85.      */
  86.     @PutMapping("/user/{id}")
  87.     public ResponseEntity<ResultVO> updateUser(@PathVariable("id") Integer id, @RequestBody User user, HttpServletResponse response) {
  88.         User originalUser = userRepository.findOne(id);
  89.         if(originalUser == null) {
  90.             response.setStatus(404);
  91.             return ResponseEntity.ok().body(new ResultVO(10001, "用户不存在"));
  92.         }
  93.         User result = null;
  94.         try {
  95.             originalUser.setUsername(user.getUsername());
  96.             originalUser.setPassword(user.getPassword());
  97.             result = userRepository.save(user);
  98.         } catch (Exception e) {
  99.             response.setStatus(500);
  100.             ResponseEntity.ok().body(new ResultVO(10003, "更新失败！"));
  101.         }
  102.         HashMap<String,User> map = new HashMap<>();
  103.         map.put("user",result);
  104.         return ResponseEntity.ok().body(new ResultVO(0, "操作成功！", map));
  105.     }
  107.     /**
  108.      * 删除用户
  109.      *
  110.      * @param id
  111.      * @param response
  112.      * @return
  113.      */
  114.     @DeleteMapping("/user/{id}")
  115.     public ResponseEntity<ResultVO> deleteUser(@PathVariable("id") Integer id, HttpServletResponse response) {
  116.         try {
  117.             userRepository.delete(id);
  118.         } catch (Exception e) {
  119.             response.setStatus(404);
  120.             return ResponseEntity.ok().body(new ResultVO(10001,"用户不存在！"));
  121.         }
  122.         HashMap<String,Integer> map = new HashMap<>();
  123.         map.put("id",id);
  124.         return ResponseEntity.ok().body(new ResultVO(0,"请求成功",map));
  125.     }
  128. }

备注：一定要加 @CrossOrigin(origins = "*", allowedHeaders = "*")  解决跨域问题。


三、使用 Prism 测试


1、下载 prism

prism 下载地址：http://stoplight.io/platform/prism/

windows下 下载完成后是一个 prism_windows_amd64.exe 文件



2、保存 OpenAPI 代码到文件中

将上面的代码保存为一个 json 或 yaml 文件，比如我这里保存为 swagger.yaml



3、运行之

prism_windows_amd64.exe run --mock --list --cors --spec E:\桌面\swagger.yaml





然后就可以在 swagger 里测试各种请求方式啦

备注：一定要开启跨域(即加--cors)，否则获取不到数据



















历史上的今天
七月
16日
  • 微信
  • 交流学习，服务定制
  • weinxin
  • 个人淘宝
  • 店铺名：言曌博客咨询部

  • (部分商品未及时上架淘宝)
avatar

发表评论

avatar 登录者：匿名
匿名评论，评论回复后会有邮件通知

  

已通过评论：0   待审核评论数：0