OpenAPITools / OpenAPITools/openapi-diff

Bug: erroneous detection of changes with mediaTypes, failure to generate html/markdown reports

未关闭
#805 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

主要语言
Java
星标
1.1k
派生
190
PR 合并指标
30 天内没有已合并 PR

描述

Hello

I've run into an interesting problem with version 2.1.2 of openapi-diff. I've redacted/dumbed down this example spec to be the smallest piece possible.
It would seem that in this case, where the content of then endpoint is uses mediaType's, changes are being detected (though not breaking) but even when the specs are identical.

I boiled the repro to the simplest form, you can take this example, put it in two separate files, and diff them with 2.1.2 (or 2.1.1 - but for instance, 2.1.0.beta-11 does NOT exhibit this)

openapi: '3.0.3'
info:
  license:
    name: ''
  termsOfService: ''
  title: "my test service"
  version: 'Latest'
tags:
  - name: mytestTag
    description: endpoints
paths:
  /v4/mytest/formats/{downloadFormat}/records/{recordId}:
    get:
      tags:
        - mytestTag
      summary: Converts record to provided format
      operationId: getV4DownloadsFormatsRecords
      deprecated: false
      x-ebsco-secured-endpoint:
        requiredScopes: [ ]
      security:
        - Authorization: [ ]
      parameters:
        - name: downloadFormat
          in: path
          description: Export format
          required: true
          schema:
            type: string
          example: 'csv'
        - name: recordId
          in: path
          description: Unique record identifier
          required: true
          example: 'ax74x2wyin'
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            text/csv:
              schema:
                type: string
                format: byte
              example: 'blah'
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                type: string
                format: byte
              example: 'blah'
            application/pdf:
              schema:
                type: string
                format: byte
              example: 'blah'
            application/x-bibtex:
              schema:
                type: string
                format: byte
              example: 'blah'
            application/marc:
              schema:
                type: string
                format: byte
              example: 'blah'
            text/xml:
              schema:
                type: string
                format: byte
              example: 'blah'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: 'BadRequest'
      content:
        application/json:
          example:
            name: BAD_REQUEST
            details:
              - field: '#/login/username'
                issue: BAD_REQUEST
                location: body
            debugId: '123456789'
            message: Request contains errors
            informationLink: 'http://developer.foo.com/apidoc/blah#BAD_REQUEST'
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: 'NotFound'
      content:
        application/json:
          example:
            name: NOT_FOUND
            details:
              - field: '#/login/username'
                issue: USERNAME_IS_NOT_FOUND
                location: body
            debugId: '123456789'
            message: Item is not found
            informationLink: 'http://developer.foo.com/apidoc/blah#USERNAME_IS_NOT_FOUND'
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: 'Unauthorized'
      content:
        application/json:
          example:
            name: UNAUTHORIZED
            details:
              - field: '#/login/username'
                issue: NOT_AUTHORIZED
                location: body
            debugId: '123456789'
            message: User is not authorized
            informationLink: 'http://developer.foo.com/apidoc/blah#NOT_AUTHORIZED'
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: 'Forbidden'
      content:
        application/json:
          example:
            name: FORBIDDEN
            details:
              - field: '#/login/username'
                issue: FORBIDDEN
                location: body
            debugId: '123456789'
            message: Access denied
            informationLink: 'http://developer.foo.com/apidoc/blah#FORBIDDEN'
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      description: Common Error response
      x-examples:
        example-1:
          name: VALIDATION_ERROR
          details:
            - field: '#/login/username'
              issue: REQUIRED_FIELD_MISSING
              location: body
          debugId: '123456789'
          message: Invalid data provided
          informationLink: 'http://developer.foo.com/apidoc/blah#VALIDATION_ERROR'
  securitySchemes:
    Authorization:
      description: Authorization token
      type: http
      scheme: bearer
      bearerFormat: JWT

This will result in changes being detected, specifically around the mediaTypes

Image

So the detection of changes when the files are identical is curious.. but furthermore, attempting to generate the html or markdown version of the report fails generate with the following exception (for markdown)

Unexpected exception. Reason: Cannot invoke "org.openapitools.openapidiff.core.model.ChangedSchema.isDiscriminatorPropertyChanged()" because "schema" is null

and for html

Unexpected exception. Reason: Cannot invoke "org.openapitools.openapidiff.core.model.ChangedSchema.isIncompatible()" because "schema" is null

When running the command like so:

java -jar openapi-diff-cli-2.1.2-all.jar anothertest.yaml samefile.yaml --html blah.html --fail-on-incompatible

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

首先,使用提供的 OpenAPI YAML 和命令 java -jar openapi-diff-cli-2.1.2-all.jar anothertest.yaml samefile.yaml --html blah.html --fail-on-incompatible 重现该报告。检查 mediaTypes 比较以及 HTML/Markdown 报告路径;当相同的规范不显示任何更改,并且两种报告格式都能生成且不会出现空指针异常时,即表示完成。

由索引模型根据 Issue 内容生成。

评估

技术栈
java
领域
api, cli
Issue 类型
缺陷
难度
3/5
预计耗时
1-2 天
活跃度
停滞
描述清晰度
基本清楚
新手友好度
45/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。