まず、なぜ闊歩を使用

インターネット技術の発展に伴い、今サイトの基本的なアーキテクチャは、元のバックエンドレンダリングからあり、それは次のようになります。フロントエンドレンダリング、単離された形のバックエンド、フロントエンド技術とバックエンド技術彼らの方法で遠く遠く。

リンクのみのフロントとリア、APIインターフェースに、リンクへのAPIドキュメントは、ますます重要になってきている、あなたのAPIドキュメントを書くためのより良い枠組みを作る闊歩し、フロントとバックエンドの開発者に連絡します。

なしAPIドキュメントツールの前に、我々は対応するライトの下readme.mdプロジェクトディレクトリにあり、合流にあっ書いて、どこかに書かれた、手書きのAPIドキュメントは、すべての企業は、すべてを持っています同社のゲームは、良くも悪くもないが再生されます。

書き込みAPIドキュメントツールは数多くありますが、唯一の闊歩推定「フレームワーク」と呼ばれることができます。

第二に、サービスの構成闊歩

ネットコア3.1を構築するために、そして意志を示すものではありません1、APIプロジェクト

図2に示すように、参照パケットNuget

右プロジェクトの依存関係] - > [管理Nugetパッケージ - >参照 - >「Swashbuckle.AspNetCore」を検索 - >最新バージョンをインストールするには、インストール

インストールが闊歩を見るために完了した後だけにNuget依存プロジェクトで導入

3、コンフィギュレーション・サービス

オープンStartup.csクラス、メソッド編集ConfigureServices

// このメソッドはランタイムによって呼び出されます。コンテナにサービスを追加するには、このメソッドを使用します。
        公共 のボイドConfigureServices（IServiceCollectionサービス）
        { 
            services.AddControllers（）; 

            #region闊歩
            services.AddSwaggerGen（C => 
            { 
                c.SwaggerDoc（" V1 "、新たな Microsoft.OpenApi.Models.OpenApiInfo {タイトル= " マイAPI "、バージョン= " V1 " }）; 
            }）; 
            #endregion 
        }

3、スタートのHttpミドルウェア

編集の設定方法

公共の 無効設定（IApplicationBuilderアプリ、IWebHostEnvironment ENV）
        { 
            // 判断是否是环境变量
            場合（env.IsDevelopment（））
            { 
                app.UseDeveloperExceptionPage（）; 
            } 

            #region闊歩
            app.UseSwagger（）。
            app.UseSwaggerUI（C => 
            { 
                c.SwaggerEndpoint（" /swagger/v1/swagger.json "、" マイAPI V1 " ）; 
            }）; 
            #endregion 

            app.UseRouting（）。

            app.UseAuthorization（）;

            app.UseEndpoints（エンドポイント => 
            { 
                endpoints.MapControllers（）; 
            }）; 
        }

4、効果を確認するために

そのために、ドメイン名入力/闊歩以下、闊歩を完了するために、デバッガを実行するF5キーを追加されている、例えばます。http：// localhost：54067 /闊歩/ index.htmlをヒットが入り、それが出てきました

5、直接アクセスにデフォルトのホーム・ページを設定する - 本番環境を

ドメイン名の後ろにすべての手動入力/闊歩、多くの問題！

闊歩この拡張機能を提供してくれて、私たちは、闊歩のアドレスとして設定におけるミドルウェアの構成をヌル文字を指定することができます。

           #region swagger 
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

                c.RoutePrefix = "";//路径配置，设置为空，表示直接访问该文件，表示直接在根域名（localhost:8001）访问该文件
                //这个时候去launchSettings.json中把"launchUrl": "swagger/index.html"去掉， 然后直接访问localhost:8001/index.html即可        
            });
            #endregion

然后再把我们上边的项目文件 launchSettings.json 的 launchUrl 给去掉就行了，这样我们无论是本地开发环境，还是生产环境，都可以默认首页加载了。

这时候会发现没有注释，如果有注释可读性就很好了，下面开始实现注释

6、显示注释

1、给接口加一个注释

        /// <summary>
        /// ID 获取Json列表
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        [HttpGet("{id}")]
        public IEnumerable<WeatherForecast> Get(int id)

2、右键点击项目---->属性------>生成------>勾选xml文档文件

3、在startup类中的ConfigureServices 方法中的服务集合中添加如下代码

            #region swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
                
                var basePath = AppContext.BaseDirectory;

                var xmlPath = Path.Combine(basePath, "Blog.Core.xml");
                c.IncludeXmlComments(xmlPath, true); //添加控制器层注释（true表示显示控制器注释）
            });
            #endregion

4、运行项目并访问swaggerUI

可以显示注释了

7、对 Model 也添加注释说明

新建一个.net core 类库Blog.Core.Model，注意是 .net core的类库，或者使用标准库也是可以的！（标准库可以在 NetCore 和 Framework 两个项目都可以跑）

然后新建一个model

    /// <summary>
    /// 这是爱
    /// </summary>
    public class Love
    {
        /// <summary>
        /// id
        /// </summary>
        public int Id { get; set; }
        /// <summary>
        /// 姓名
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 年龄
        /// </summary>
        public int Age { get; set; }
    }

1、当前 api 层直接引用了 Blog.Core.Model 层；

2、Blog.Core.Model 右键属性配置 xml

3、导入model.xml到swagger

// This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            #region swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
                
                var basePath = AppContext.BaseDirectory;

                var xmlPath = Path.Combine(basePath, "Blog.Core.xml");
                c.IncludeXmlComments(xmlPath, true); //添加控制器层注释（true表示显示控制器注释）

                var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");
                c.IncludeXmlComments(xmlModelPath, true);
            });
            #endregion
        }

接口添加注释

        /// <summary>
        /// post
        /// </summary>
        /// <param name="love">model 实体类</param>
        [HttpPost]
        public void Post(Love love)
        { 
            
        }

重新运行就出来了

8、隐藏某些接口

如果不想显示某些接口，直接在controller 上，或者action 上，增加特性

[ApiExplorerSettings(IgnoreApi = true)]

        /// <summary>
        /// post
        /// </summary>
        /// <param name="love">model 实体类</param>
        [HttpPost]
        [ApiExplorerSettings(IgnoreApi =true)]
        public void Post(Love love)
        { 
            
        }


Post方法就不显示了

三、结语

下一篇 Swagger JWT 权限，给接口加权限验证

ネットCore3.1が闊歩を追加します