Microsoft OpenAPI.NET 开源项目安装与使用指南-CSDN博客

本文链接：https://blog.csdn.net/gitblog_01080/article/details/141150956

Microsoft OpenAPI.NET 开源项目安装与使用指南

OpenAPI.NETThe OpenAPI.NET SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model.项目地址:https://gitcode.com/gh_mirrors/op/OpenAPI.NET

目录结构及介绍

当你克隆或下载了OpenAPI.NET项目库后,你会看到以下主要目录:

Root Directory

这个根目录包含了整个OpenAPI.NET SDK.它包括以下子目录和文件:

`src`

这是一些主要代码实现的位置，比如对OpenAPI文档的读取、解析和序列化的功能。

`tests`

这是一个单元测试和集成测试文件存放的地方.

`docs`

这里是所有文档都保存在其中的目录.

`samples`

此目录包含示例应用程序来演示如何使用SDK。

`README.md`

这是项目的主要入门点，提供了关于OpenAPI.NET SDK的重要说明和快速指南。

`LICENSE`

这个是开源协议许可文件。

`.gitignore`

这是一个由.git版本控制管理器使用的特殊文件，以指示哪些文件应该被忽略。

启动文件介绍

OpenAPI.NET没有特定的“启动”文件，因为它主要是作为一个库使用于其他.NET应用中。然而，在samples目录下你可以找到名为Program.cs或Startup.cs等样例项目中的主入口文件。这些文件可以看作是启动应用程序并加载OpenAPI文档的起点。

以位于samples下的SimpleExample为例：

// Program.cs 或 Startup.cs 示例代码
using Microsoft.OpenApi.Models;
using System;
using System.IO;

namespace SimpleExample
{
    public class Program
    {
        static void Main(string[] args)
        {
            string json = File.ReadAllText("path/to/openapi.json");
            var openApiDoc = new OpenApiDocument();
            var reader = new OpenApiStreamReader();
            using (var documentReader = new JsonTextReader(new StringReader(json)))
            {
                reader.Read(documentReader, openApiDoc);
            }

            Console.WriteLine(openApiDoc.Paths.Count); // 打印路径的数量
            
            // 进一步操作或使用openApiDoc...
        }
    }
}

该程序将从本地文件系统加载一个OpenAPI规范文件（例如json格式），然后通过OpenApiStreamReader类将其转换成OpenApiDocument对象进行处理。

配置文件介绍

OpenAPI.NET SDK本身不需要任何配置文件即可运行;但是当作为Web API的一部分使用时，可以通过ASP.NET Core配置中间件来指定OpenAPI文档的路径和详细信息。

以下是可以在ASP.NET Core项目中创建的一个简单示例appsettings.json文件，用于配置Swagger UI和其他细节：

{
  "OpenApi": {
    "Title": "My Web Api",
    "Version": "v1",
    "JsonPath": "swagger/v1/swagger.json", // OpenAPI 文档的路径
    "Description": "This is a sample web api."
  },
  "Logging": {
    ...
  },
  ...
}

随后你需要在ConfigureServices方法中设置Swagger服务:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // Add Swagger services.
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = Configuration["OpenApi:Title"], Version = Configuration["OpenApi:Version"] });
        
        // Other configurations...
    });

    ...
}

而在你的Configure方法里激活Swagger UI:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });

    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", Configuration["OpenApi:Title"]);
    });
}

总结来说，虽然OpenAPI.NET SDK本身不需要复杂的配置流程，但是在实际的应用场景中，如集成到ASP.NET Core项目内时，则可能需要额外的设置步骤来定义Web API的接口描述以及提供友好的交互界面，比如使用Swagger UI。