Hello,
Firstly, thank you so much for the 3.0 support!!!

Is it possible to add the line number of the source file where a breaking change is found?
This is what the Swagger 2.0 tool - https://github.com/Azure/openapi-diff is able to do.

Thanks!

Is OpenAPI version 3.1 supported with this lib?

Hello,

I want to have the possibility to give an URL to download the swagger spec instead of a local file.

I modify the Program.cs of the Criteo.OpenApi.Comparator.Cli like this:

`// Copyright (c) Criteo Technology. All rights reserved.
// Licensed under the Apache 2.0 License. See LICENSE in the project root for license information.

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text.Json;

namespace Criteo.OpenApi.Comparator.Cli
{
///

        if (parserResult.Errors.Any())
        {
            return 1;
        }

        var options = parserResult.Value;

        var oldFileFound = TryReadFile(options.OldSpec, out var oldOpenApiSpecification);
        var newFileFound = TryReadFile(options.NewSpec, out var newOpenApiSpecification);

        if (!oldFileFound || !newFileFound)
        {
            Console.WriteLine("Exiting.");
            return 1;
        }

        var differences = OpenApiComparator.Compare(oldOpenApiSpecification, newOpenApiSpecification);

        DisplayOutput(differences, options.OutputFormat);

        return 0;
    }

    private static bool **TryReadFile**(string path, out string fileContent)
    {
        bool readOk = TryReadDistantFile(path, out fileContent);
        if (!readOk)
        {
            TryReadLocalFile(path, out fileContent);
        }
        return readOk;
    }

    private static bool **TryReadDistantFile**(string url, out string fileContent)
    {
        try
        {
            using HttpClient wc = new HttpClient();
            fileContent = wc.GetStringAsync(url).Result;
            return true;
        }
        catch (Exception e)
        {
            Console.WriteLine($"File not found for: {url} with the message {e.Message}");
            fileContent = null;
            return false;
        }
    }

    private static bool **TryReadLocalFile**(string path, out string fileContent)
    {
        try
        {
            fileContent = File.ReadAllText(path);
            return true;
        }
        catch (FileNotFoundException f)
        {
            Console.WriteLine($"File not found for: {path} with the message {f.Message}");
            fileContent = null;
            return false;
        }
    }

    private static void DisplayOutput(IEnumerable<ComparisonMessage> differences, OutputFormat outputFormat)
    {
        if (outputFormat == OutputFormat.Json)
        {
            Console.WriteLine(JsonSerializer.Serialize(differences, new JsonSerializerOptions { WriteIndented = true }));
            return;
        }

        foreach (var change in differences)
        {
            if (outputFormat == OutputFormat.Text)
            {
                Console.WriteLine(change);
            }
        }
    }
}

}
`

Could you integrate it?

Thanks

How about create executable, for using in scripts on PC without dotnet tools?

We have a mix of v3 and v2 versions, are the tool capable of comparing both versions?

Would it be possible to add support for YAML? YAML is a common format for OpenAPI specifications, and mostly similar to JSON.

Why

For now, when two schemas are compared, if one of them is null, a misleading ArgumentNullException is thrown during the comparison, which makes the comparison crash without any precise message.

But, if the new OR old schema is null, it actually means that the schema was removed OR added, a Breaking Change should be reported instead of throwing an exception.

What/How

While comparing a new and an old schema:

• If the new schema is null, but not the old one, the schema is removed, then a RemovedSchema breaking change should be added to the context instead of throwing an ArgumentNullException

• If the old schema is null, but not the new one, the schema is removed, then an AddedSchema breaking change should be added to the context instead of throwing an ArgumentNullException

• The AddedSchema comparison rule must be created and properly documented

Acceptance Criteria

• When two OAS are compared, if a schema is missing in the new OAS, but is present in the old one, Then a RemovedDefinition difference should be returned as part of the comparison result

• When two OAS are compared, if a schema is missing in the old OAS, but is present in the new one, Then an AddedSchema difference should be returned as part of the comparison result

• The documentation for the AddedSchema comparison rule should be accessible here.

Example:
"Message": "The optional parameter \u0027\u0027 was added in the new version.",

Full content:
{
"Severity": 1,
"Message": "The optional parameter \u0027\u0027 was added in the new version.",
"OldJsonRef": "#/paths/1subscriptions1{id}~1transactions/get/parameters/0",
"NewJsonRef": "#/paths/1subscriptions1{id}~1transactions/get/parameters/0",
"Id": 1043,
"Code": "AddingOptionalParameter",
"Mode": 0
}

What can I do to have the unicode chars shown in the clear?
Thanks!

The doc url displayed from a comparison message is broken. Example :
https://github.com/Azure/openapi-diff/tree/master/docs/rules/10021.md
https://github.com/Azure/openapi-diff/tree/master/docs/rules/10281.md

To reproduce :

...
var comparator = new OpenApiComparator();
var messages = comparator.Compare(oldFileName, oldOpenApiSpec, newFileName, newOpenApiSpec);
foreach(var message in messages)
{
    Console.WriteLine(message);
}

Output :

..., docurl = https://github.com/Azure/openapi-diff/tree/master/docs/rules/10021.md, mode = Removal
..., docurl = https://github.com/Azure/openapi-diff/tree/master/docs/rules/10281.md, mode = Update
..., docurl = https://github.com/Azure/openapi-diff/tree/master/docs/rules/10281.md, mode = Update

It seems that the problem comes from ComparisonMessage._docBaseUrl. The base doc url is "https://github.com/Azure/openapi-diff/tree/master/docs/rules".

All rules are replicated in this repository, I suggest that comparison message doc url redirect directly to "https://github.com/criteo/openapi-comparator/tree/{version}/documentation/rules".

Do you want some help? I can do the pull request.

Hello,
In https://github.com/Azure/openapi-diff/blob/main/docs/rules/1006.md, we see that the above error is detected.
This comes from swagger 2.0.

Is such an error (RemovedDefintion) returned from Criteo if it's fed a swagger 2.0 files?
Thanks!

Hello,

I would like to have the RequiredStatusChange fail for requests and responses, as for now there is no errors for the following contract change:

"MyEntityName": {
      "required": [
        "myProperty1",
-       "myProperty2"
      ],

I checked the implementation, and it bypasses the check for responses:

 if (oldParameter.IsRequired() == newParameter.IsRequired() || context.Direction == DataDirection.Response)
                return;

The description of the rule, "Checks whether an existing property's required status is changed from the previous specification.", doesn't mention anything about this bypass. Furthermore, I believe changing the "required" status in a response is a breaking change as well.

I'll see if I can investigate and push a PR later on.

I have two simplest files below:

old_openapi.json:
{
"openapi": "3.0.0",
"info": {
"title": "foos",
"version": "1.5"
}
}

new_openapi.json:
{
"openapi": "3.0.0",
"info": {
"title": "foos",
"version": "1.4"
}
}

I run the compare as follows:
openapi-compare -o old_openapi.json -n new_openapi.json

Output:
[
{
"Severity": 2,
"Message": "The new version has a lower value than the old: System.String[] -\u003E System.String[]",
"OldJsonRef": "#/info/version",
"NewJsonRef": "#/info/version",
"Id": 1000,
"Code": "VersionsReversed",
"Mode": 1
}
]

Instead of printing 1.4 and 1.5, it printed some garbled text in the "Message" field.
Could you please let know what's causing it and how to fix it?

Thanks!