如果您的应用程序开发中有Swagger定义，请使用Prism


一个故事，如果后端人员在智能手机应用程序的开发中使用Swagger定义(也称为Open API Spec)，则应使用Prism。

什么是棱镜？

https://stoplight.io/open-source/prism/

  • 它是由一家名为Stoplight的公司生产的。我们提供各种工具来促进API开发。
  • Prism是这些工具之一，即所谓的模拟服务器。它作为OSS提供。
  • 如果这是另一项服务，则原始Swagger UI也可以模拟响应，并且还提供API Sprout。

安装与使用

1
2
$ npm install -g @stoplight/prism-cli
$ prism mock swagger.yaml

就是这样。简单。默认情况下，它使用127.0.0.1:4010端口，如果更新正在读取的swagger定义文件，它将自动重新加载。 (这不在Swagger UI模拟服务器上)

响应定制

如果在要响应的Swagger定义中写入example，它将返回以下响应。
如果您听不懂，请阅读原始文档。
https://swagger.io/docs/specification/adding-examples/

方法1：分别设置example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
(略)
components:
  schemas:
    Pet:
      allOf:
        - $ref: '#/components/schemas/NewPet'
        - type: object
          required:
          - id
          properties:
            id:
              type: integer
              format: int64
              example: 123  # <-- これ

    NewPet:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: foo  # <-- これ
        tag:
          type: string
          example: bar  # <-- これ

方法2：一起设置example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
(略)
components:
  schemas:
    Pet:
      example:  # <-- これ
        id: 999
        name: hoge
        tag: moge
      allOf:
        - $ref: '#/components/schemas/NewPet'
        - type: object
          required:
          - id
          properties:
            id:
              type: integer
              format: int64

    NewPet:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        tag:
          type: string

注意

如果同时设置了方法1和2，会发生什么？

在

Prism的情况下，方法2的定义优先。

违反响应定义的example的值是否会导致错误？

如果是棱镜，则不会发生任何错误。当心。

离题

起初我尝试使用API?? Sprout，但是似乎存在一个错误，我无法很好地使用$ref处理定义，并且我放弃了，因为Github上的问题已经存在了一年多了。
https://github.com/danielgtaylor/apisprout/issues/40

我希望它可以帮助某人。