json-api-dotnet
Umbrella: OpenAPI integration
OpenAPI integration
This document provides an overview of the work items involved in creating an OpenAPI integration for JsonApiDotNetCore.
Disclaimer: this is an open source project. The available time of our contributors varies and therefore we do not plan release dates. This document expresses our current intent, which may change over time.
Approach
Creating an OpenAPI integration for JsonApiDotNetCore requires setting up a mechanism that generates an OpenAPI Specification (OAS) file from application code. This file allows for automatic generation of API docs (see eg. SwaggerUI) and client code (see eg. NSwag code generator). In the design choices for this mechanism, precedence will be given to compatibility with client code generation tools, because we believe this to be of the biggest impact to the JSON:API community (see eg. this discussion and others).
In a private repository, we have experimented for several months with integrating Swashbuckle's SwaggerGen in a JsonApiDotNetCore application. We have decided to extract this code into this repository and move forward from there.
Work items
Pending
The order of the list below reflects the order in which we intend to address the work items.
- #1056
- #1063
- #1051
- #1065
- #1066
- #1067
- #1461
- #1575
- #1576
You can try the latest build at https://github.com/json-api-dotnet/JsonApiDotNetCore/pkgs/nuget/JsonApiDotNetCore.OpenApi.Swashbuckle (requires a PAT, see here for setup).
Delivered in preview 1
- #1031
- #1047
- #1048
- #1049
- #1050
- #1080
- #1111
- #1053
- #1058
- #1059
- #1061
- #1115
- #1233
- #1052
- #1057
- #1243
- #1458
- #1367
- #1456
- #1054
- #1062
- #1060
- #1055
- #1572
- #1578
- #1577
- #1457
- #1626
- #1686
Feedback
The best way to give feedback is to create new issues or upvote/downvote existing ones. Please give us feedback that will give us insight into the following points:
- Existing features that are missing some capability or otherwise don't work well enough.
- Missing features that should be added to the product.
- Design choices for a feature that is currently in progress.
For anyone that wants to try out the latest bits: pick a version with "openapi" in the name from https://github.com/json-api-dotnet/JsonApiDotNetCore#trying-out-the-latest-build.
For anyone that wants to try out the latest bits: pick a version with "openapi" in the name from https://github.com/json-api-dotnet/JsonApiDotNetCore#trying-out-the-latest-build.
Hello, I wanted to try this out, however I am facing a bug, as shown below.
I was using the docs in the openapi branch (here), and looking at the tests startup.
As for the version, this is from the AppVeyor 5.1.1-openapi-0956.
I understand this is a work in progress, let me know if this is legit bug or just my config that failed, I'll open a new issue to be tracked.
Unhandled exception.
System.MethodAccessException: Attempt by method 'JsonApiDotNetCore.OpenApi.ServiceCollectionExtensions.AddOpenApi(Microsoft.Extensions.DependencyInjection.IServiceCollection, Microsoft.Extensions.DependencyInjection.IMvcCoreBuilder, System.Action`1<Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenOptions>)'
to access method 'JsonApiDotNetCore.ArgumentGuard.NotNull<Microsoft.Extensions.DependencyInjection.IServiceCollection>(Microsoft.Extensions.DependencyInjection.IServiceCollection, System.String)' failed.
at JsonApiDotNetCore.OpenApi.ServiceCollectionExtensions.AddOpenApi(IServiceCollection services, IMvcCoreBuilder mvcBuilder, Action`1 setupSwaggerGenAction) in C:\projects\jsonapidotnetcore\src\JsonApiDotNetCore.OpenApi\ServiceCollectionExtensions.cs:line 21
Program.cs
using System.Reflection;
using JsonApiDotNetCore.Configuration;
using JsonApiDotNetCore.OpenApi;
using Microsoft.EntityFrameworkCore;
using Microsoft.OpenApi.Models;
using ROSA.Context;
var builder = WebApplication.CreateBuilder(args);
var connectionString = builder.Configuration.GetValue<string>("ConnectionStrings:RosaApiDatabase") ??
throw new InvalidOperationException();
builder.Services.AddDbContext<RosaDbContext>(options => { options.UseSqlite(connectionString); });
builder.Services.AddSwaggerGen();
var mvcBuilder = builder.Services.AddMvcCore();
builder.Services.AddJsonApi<RosaDbContext>(mvcBuilder: mvcBuilder);
builder.Services.AddOpenApi(mvcBuilder);
var app = builder.Build();
app.UseRouting();
app.UseJsonApi();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();
@sharky98 Please move your question to a separate issue (and provide the requested details), this is not the place.
JetBrains Rider has built-in IDE support for OpenAPI, see https://www.jetbrains.com/help/rider/OpenAPI.html. Similar feature in Visual Studio Preview: https://devblogs.microsoft.com/visualstudio/web-api-development-in-visual-studio-2022/#endpoints-explorer
How to configure the NSwag C# client generator: https://github.com/RicoSuter/NSwag/wiki/NSwag-Configuration-Document and https://stevetalkscode.co.uk/openapireference-commands and https://github.com/RicoSuter/NSwag/blob/master/src/NSwag.CodeGeneration.CSharp/CSharpClientGeneratorSettings.cs.
@bkoelman what's the status of the OpenAPI integration? I could have a look if there is a isolated issue about it.
@verdie-g The OpenAPI integration is my primary priority. Picking up from @maurei's work, I've recently implemented support for triple-slash doc-comments, query string parameters, and included related resources in responses.
I've updated the list of work items and marked several with the good first issue label. Feel free to give it a try.
Happy to see this work is being picked up again! I wish I could devote a few months of my time to this again :-)