openapi

openapi

基本结构

登录认证

swagger2.0 是这样的

securityDefinitions:
  apiKey:
    type: apiKey
    name: token
    in: header
security:
  - apiKey: []

openapi3.0是这样的

https://stackoverflow.com/questions/29817270/using-an-api-key-secret-for-swagger-security-scheme

components:
  securitySchemes:
    key: 
      type: apiKey
      name: token
      in: header
    secret_key:
      type: apiKey
      name: SecretKey
      in: header

除此之外，每个路径都要添加如下：（保持空就可以，在界面上填一下就ok了）

/records/api_token:
  get:
    security:
      - key: []
      - secret_key: []

如果上面两个都设置了，大概会是这样的：

这个是用的是SecretKey，两个都生效的效果。

curl -X 'GET' \
  'http://qingcloud.yundasys.com/backend/web/myadmin.php/records/api_token' \
  -H 'accept: application/json' \
  -H 'token: ffdfdfrZ' \
  -H 'SecretKey: 23232'

返回文档的格式content-type

如果需要对返回的文档格式化，比如 json更美观一些，必须要返回content-type: application/json。

content-type: application/json; charset=utf-8 

动态字段问题

https://learnku.com/articles/51251

additionalProperties是关键

definitions:
  deployImagesItem:
    type: object
    additionalProperties: 
      type: array
      items: 
        type: object
        properties:
          images:
            type: string
            example: 10.131.9.12:5000/qingcloud/cloud-teacher:4.5.3_f7b9970
          created_time:
            type: string
            example: '2021-06-25 11:52:16'

当然，另外一种方式，是消除动态字段。将结果包裹在稳定的结构中。

按如下方式，重新封装一下。

[
	{
		'key':"原来的动态字段",
        'list':[
            {....}
        ]
	}

]