microsoft/OpenAPI.NET.CSharpAnnotations

IT DOESN'T WORK!

PeterAnaniaHC opened this issue · 3 comments

PeterAnaniaHC commented

At all. You do exactly what the documentation says. You read your own XML document (you can even copy the XML document in the documentation and input that) and none of the members are translated into endpoints in the open api doc. It doesn't WORK!

Graz21 commented

Hey there,

I've just tested it out and it works. Make sure you've annotated your endpoints correctly.

Also you can check if there were errors during schema generation by inspecting the GenerationDiagnostic class.

Example of endpoint annotation:

/// <summary>
/// Load book by Id or Name
/// </summary>
/// <group>Books</group>
/// <verb>GET</verb>
/// <url>http://localhost:99/publicapi/books/{identifier}</url>
/// <param name="identifier" cref="string" in="path">Book id or name</param>
/// <response code="200"><see cref="BookDTO"/>Sample object retrieved</response>
[HttpGet]
public IHttpActionResult Get(string identifier)
{
    /* your code here */
}

Example for schema generation:

public string GenerateSchema() {

    var input = new OpenApiGeneratorConfig(
        annotationXmlDocuments: new List<XDocument>()
        {
            XDocument.Load(@"bin\project.xml") // your project xml
        },
        assemblyPaths: new List<string>()
        {
            @"bin\project.dll" // your project dll
        },
        openApiDocumentVersion: "V1",
        filterSetVersion: FilterSetVersion.V1
    );

    GenerationDiagnostic result;

    var generator = new OpenApiGenerator();

    IDictionary<DocumentVariantInfo, OpenApiDocument> openApiDocuments = generator.GenerateDocuments(
        openApiGeneratorConfig: input,
        generationDiagnostic: out result
    );

    // Check result for errors in:
    // OperationGenerationDiagnostic.Errors

    return openApiDocuments.First().Value.SerializeAsJson(OpenApiSpecVersion.OpenApi3_0);
}

One thing I've noticed is that if you have complex types, like BookDTO in my case, its properties must have a getter and setter.

PeterAnaniaHC commented

Thank you very much for your time, but I was able to get it to work eventually. The issue I was having was a library conflict. I'm using .Net Core 3.1 and I was using the Microsoft.Extensions.Configuration NuGet package, but the two together (Open Api and the Extension) caused the solution to crash every time. I had to remove one of them, and since I needed the Open API document in order to expose the Azure function through the API Manager, I choose to keep the Open Api Generator. It was a little extra work, but as I said in the end I was able to get it to work.

It was aggravating though, because there were no library conflict warnings or errors and I literally had to start with a new application, add this library first then add every other package one at a time to find the issue. Arrggh.

In the end I think the issue is a conflict with the particular set of technologies I was using, not so much this library itself.

Again, thank you for your time, Peter

PeterAnaniaHC commented