APIs-guru / openapi-directory

🌐 Wikipedia for Web APIs. Directory of REST API definitions in OpenAPI 2.0/3.x format

https://apis.guru/

Creative Commons Zero v1.0 Universal

3.88k stars 578 forks source link

A few broken $ref s #785

Open hrennau opened 3 years ago

hrennau commented 3 years ago

In the OAS documents downloaded today (2021-03-09), a few references were observed:

Resource
azure.com:network-virtualNetwork.json
.  ./networkInterface.json#/definitions/NetworkInterfaceTapConfiguration
docusign.net.json
.  #/definitions/offlineAttributes
payrun.io.json
.  #/definitions/JournalExpressionDataTable
.  #/definitions/ThirdPartyTransaction
shutterstock.com.json
.  #/components/schemas/AssetId
.  #/components/schemas/AssetUploadId
squareup.com.json
.  #/components/schemas/invoice_delivery_methodInvoiceDeliveryMethod
statsocial.com.json
.  #/definitions/18_24
.  #/definitions/25_34
.  #/definitions/35_44

MikeRalphson commented 3 years ago

Thanks for this! Can you let me know what tool you are using to validate the definitions?

DocuSign, PayRun, ShutterStock, SquareUp all should be fixed now.

The Azure one we know about (see issue #540)

StatSocial - can you check again, this one looks ok to me?

hrennau commented 3 years ago

Just checked StatSocial again, the version downloaded per REST service at 10AM CET. I see the following references:

/definitions/18_24

/definitions/25_34

/definitions/35_44

But the schema names in "definitions" are: 1824 2534 3544

hrennau commented 3 years ago

Mike, could it be that the new versions are not yet delivered by the REST service? At any rate, I find the old ref errors, as well as a couple of new errors - see attachment. invalid-references.20210318.txt

MikeRalphson commented 3 years ago

Yes, the CI run was probably still going when you checked. I'll have a look at your latest list. Thanks.

MikeRalphson commented 3 years ago

Re: statsocial, I'm not sure what is eating the underscores, but here the definitions look like:

         description: "Possible reasons include:<br>{success: 0, msg: Error requesting twitter info, error_code_msg: API_TWITTER_ERROR}<br>{success: 0, msg: Error inserting new twitter report, error_code_msg: API_ERROR_CREATING_TWITTER_ACCOUNT}<br>{success: 0, msg: Error getting application's credentials, error_code_msg: API_ERROR_GETTING_APPLICATION_INFO}}<br>{success: 0, msg: Internal database error, error_code_msg: API_ERROR_DATABASE_INITIATION_ERROR}"
          schema:
            $ref: "#/definitions/500_Error"
      summary: Used to create twitter follower report
      tags:
        - Follower Reports
definitions:
  18_24:
    properties:
      average:
        type: integer
      multiplicity:
        type: integer
      percentile:
        type: integer
      statistical_info:
        $ref: "#/definitions/statistical_info_18"

MikeRalphson commented 3 years ago

Fixed the apigee.local/registry definition (same cause). The CI run will take at least 50 minutes from now.

hrennau commented 3 years ago

Will now travel a little and tonight will repeat the check and let you know.

hrennau commented 3 years ago

Good morning and good news, Mike - data almost clean now, excepting known issues (azure and statsocial).

azure.com_network-virtualNetworkTap.json
.  ./networkInterface.json#/definitions/NetworkInterfaceTapConfiguration
github.com.json
.  https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc (4)
.  https://api.github.com/scim/v2/enterprises/octo-corp/Users/aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5 (2)
statsocial.com.json
.  #/definitions/18_24
.  #/definitions/25_34
.  #/definitions/35_44

The github references are not new, I had just removed them by hand in previous reports, as I thought they are caused by shortcomings of my evaluator - but I'm not quite sure, therefore I now include them.

hrennau commented 3 years ago

PS: As you asked for the tool I use for checking - it is Foxpath, an expression language for evaluating resource trees and structured resource contents (XML, JSON, CSV, HTML). The reports I showed you were created by the following expression:

fox -D "../apis/*.json\jdescendant('$ref')[not(parent::properties)][not(jref(.))]\hlist-entry(bfname(), .) => hlist()"`

MikeRalphson commented 3 years ago

I think the github.com ones you identified above are $ref values within examples. These are as-is key/value pairs in JSON/YAML example requests/responses are not actually $ref keywords which can be resolved.

statsocial.com looks fine for me.

azure.com is still pending a rearrangement of the service values / directory structure before these $refs can be fixed.