项目作者: nikolaydubina

项目描述 :
Inline OpenAPI JSON examples from filenames
高级语言: Go
项目地址: git://github.com/nikolaydubina/openapi-inline-examples.git
创建时间: 2021-04-03T03:11:13Z
项目社区:https://github.com/nikolaydubina/openapi-inline-examples

开源协议:MIT License

下载


codecov
OpenSSF Scorecard

How do I add JSON examples to openapi.yaml from .json files?

Add to your openapi.yaml annotation #source <filepath> like

  1. openapi: 3.0.0
  2. info:
  3. version: 1.0.0
  4. title: Swagger Marvelstore
  5. paths:
  6. /users:
  7. get:
  8. responses:
  9. '200':
  10. description: A user object.
  11. content:
  12. application/json:
  13. schema:
  14. type: object
  15. properties:
  16. id:
  17. type: integer
  18. format: int64
  19. example: 4
  20. name:
  21. type: string
  22. example: Jessica Smith
  23. examples:
  24. basic:
  25. value: #source testdata/user-basic.json
  26. '400':
  27. description: The specified user ID is invalid (not a number).
  28. content:
  29. application/json:
  30. examples:
  31. basic 400:
  32. value: #source testdata/error-400.json

.. then run

  1. $ go install github.com/nikolaydubina/openapi-inline-examples@latest
  2. $ cat openapi.yaml | openapi-inline-examples > openapi.new.yaml

.. which will produce

  1. openapi: 3.0.0
  2. info:
  3. version: 1.0.0
  4. title: Swagger Marvelstore
  5. paths:
  6. /users:
  7. get:
  8. responses:
  9. '200':
  10. description: A user object.
  11. content:
  12. application/json:
  13. schema:
  14. type: object
  15. properties:
  16. id:
  17. type: integer
  18. format: int64
  19. example: 4
  20. name:
  21. type: string
  22. example: Jessica Smith
  23. examples:
  24. basic:
  25. value: {"id":42,"name":"Nick Fury"} #source testdata/user-basic.json
  26. '400':
  27. description: The specified user ID is invalid (not a number).
  28. content:
  29. application/json:
  30. examples:
  31. basic 400:
  32. value: {"errors":[{"message":"resource not found","status":400,"translation_data":"some translation identifier"}]} #source testdata/error-400.json

.. which renders nicely as multiple examples that you can select

example-preview

Why would anyone need this?

  • Keep your OpenAPI up to date with values you use in tests
  • Can run multiple times
  • UNIX filter
  • Does not corrupt anything if fails at any stage
  • 100% test coverage