openapi， springdoc with Swagger注释将自由形式的应用程序/x-ows-form-urlencoded请求正文拆分为单个字符

Question

我正在尝试从Springfox迁移到springdoc，以实现我们的招摇过市页面，有一个endpoint我很难与springdoc合作。它模仿OAuth2令牌endpoint，接收一个应用程序/x-www-form-urlencoded请求体，允许使用不同的授权类型。我有下面生成的openapi文档。根据Swagger页面，当使用object类型的模式时，应该允许自由形式的数据。然而，当我传入在Springfox和swagger 2上工作的示例值时（grant_type=authorization_code）

curl -X 'POST' \
  'http://localhost:8080/v1/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d '0=g&1=r&2=a&3=n&4=t&5=_&6=t&7=y&8=p&9=e&10=%3D&11=a&12=u&13=t&14=h&15=o&16=r&17=i&18=z&19=a&20=t&21=i&22=o&23=n&24=_&25=c&26=o&27=d&28=e&29=%26&30=c&31=o&32=d&33=e&34=%3D&35=x&36=x&37=x&38=x&39=x&40=x&41=x&42=x&43=x&44=x&45=%26&46=c&47=l&48=i&49=e&50=n&51=t&52=_&53=i&54=d&55=%3D&56=x&57=x&58=x&59=x&60=x&61=x&62=x&63=x&64=x&65=x'

我在openapi yaml中是否做错了什么，或者我在大摇大摆的页面上错误地放入了请求正文？

OpenAPI YAML将在https://editor.swagger.io/使用

openapi: 3.0.1
info:
  title: Test API
  description: Testing
  version: "1.0"
servers:
  - url: http://localhost:8080
    description: Generated server url
security:
  - api: []
paths:
  /v1/token:
    post:
      tags:
        - token-controller
      description: Oauth 2 Access Token.
      operationId: getOauthAccessToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
            examples:
              authorization_code grant type:
                description: authorization_code grant type
                value: grant_type=authorization_code&code=xxxxxxxxxx&client_id=xxxxxxxxxx
              client_credentials grant type:
                description: client_credentials grant type
                value: grant_type=client_credentials&client_id=xxxxxxxxxx&client_secret=xxxxxxxxxx
              refresh_token grant type:
                description: refresh_token grant type
                value: grant_type=refresh_token&refresh_token=xxxxxxxxxx
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OauthAccessTokenResponseView_V1'
components:
  schemas:
    OauthAccessTokenResponseView_V1:
      type: object
      properties:
        scope:
          type: string
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
          format: int64
      description: 'The Oauth 2 Access Token response: https://www.oauth.com/oauth2-servers/access-tokens/access-token-response/'
  securitySchemes:
    api:
      type: http
      scheme: bearer

Answer 1

您的定义看起来不错。这是SwaggerUI中与OpenAPI 3示例关键字和表单数据相关的错误（或限制？）。请在问题跟踪器中报告：https://github.com/swagger-api/swagger-ui/issues

我找不到一种有效的方法来为表单数据提供多个示例。

从文档的角度来看，我建议更新请求主体模式，以定义准确的预期属性。下面是一个可能的变体，它使用了其中一个和属性级别示例值。但不幸的是，呈现和使用oneOf对表单数据“试用”还有其他已知问题。

      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: '#/components/schemas/AuthorizationCodeTokenRequest'
                - $ref: '#/components/schemas/ClientCredentialsTokenRequest'
                - $ref: '#/components/schemas/RefreshTokenRequest'
      ...

components:
  schemas:
    AuthorizationCodeTokenRequest:
      type: object
      required:
        - grant_type
        - code
        - client_id
      properties:
        grant_type:
          type: string
          enum: [authorization_code]
        code:
          type: string
          example: xxxxxxxxxx
        client_id:
          type: string
          example: xxxxxxxxxx
    ClientCredentialsTokenRequest:
      type: object
      required:
        - grant_type
        - client_id
        - client_secret
      properties:
        grant_type:
          type: string
          enum: [client_credentials]
        client_id:
          type: string
          example: xxxxxxxxxx
        client_secret:
          type: string
          format: password
          example: xxxxxxxxxx
    RefreshTokenRequest:
      type: object
      required:
        - grant_type
        - refresh_token
      properties:
        grant_type:
          type: string
          enum: [refresh_token]
        refresh_token:
          type: string
          format: password
          example: xxxxxxxxxx

您真的需要记录令牌endpoint的有效负载吗？如果它是符合RFC 6749的标准OAuth 2.0令牌endpoint，您可以在securitySchemes中定义它：

paths:
  /something:
    get:
      description: One of the endpoints that require OAuth Bearer token.
      security:
        - oauth2: []  # <-----
      responses:
        ...

components:
  securitySchemes:
    oauth2:           # <-----
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: '???' # TODO
          tokenUrl: /v1/token
          refreshUrl: '???' # TODO
          scopes: {}
        clientCredentials:
          tokenUrl: /v1/token
          refreshUrl: '???' # TODO
          scopes: {}