web-dev-qa-db-ja.com

Swashbuckleにクラスとプロパティの説明を含めるには、OWINを使用してWeb Api 2のSwaggerドキュメントを生成しますか？

あなたがそれを考える前に、 this は同じではありません。

これはかなり自明のはずだと思います。 Swaggerドキュメントにクラスの説明を含めたいと思います。私のSwagger設定は次のようになります。

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "My Api Name");
    c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(GetXmlCommentsPath());

}).EnableSwaggerUi(c => { });

そして、MyAwesomeControllerは次のようになります：

/// <summary>
/// Controller description (is included by Swashbuckle)
/// </summary>
public class MyAwesomeController : ApiController
{
    /// <summary>
    /// Method description (is included by Swashbuckle)
    /// </summary>
    public IHttpActionResult Get()
    {
        return Ok("hello... from the other side");
    }

    public IHttpActionResult Post([FromBody]MyAwesomeModel model)
    {
        return Ok("hello... from the other side");
    }
}

そして私のMyAwesomeModelは次のようになります：

/// <summary>
/// **I would like this to be included in the Swagger description of the parameter**
/// </summary>
public class MyAwesomeModel
{
    /// <summary>
    /// **I would like this to be included in the Swagger description of the parameter**
    /// </summary>
    public string MyProperty { get; set; }
}

Sr. Skeetを雇わなくてもこれは可能ですか？

asp.net-web-apiowinswaggerswashbuckle
11
Marcus

うーん...だから多分誰かがこれに遭遇した場合。

基本的に、これを実行できる1つの方法を見つけ、デフォルトで実行されなかった理由を理解しました。それが最善のアプローチであるかどうかはわかりませんが、ここで説明します。

私のソリューションでは、POCOは実際のAPIとは別のプロジェクトに配置されているため、クラスとプロパティのXMLノードが生成されなかったため、MyAwesomeModelのコメントの説明は含まれていませんでした。そのため、POCOが配置されていた別のプロジェクトで、プロパティを変更してXMLを生成しました。

  1. POCOが配置されているプロジェクトのXMLを生成する

Output XML for the project where model classes are located

  1. XMLがSwashbuckleで検索するパスにコピーされていることを確認してください。プロジェクトのプロパティで_Post-build event command line_を使用しました。

copy "$(SolutionDir)MyAwesomeProjectWithPocos\bin\MyAwesomeProjectWithPocos.xml" "$(ProjectDir)\bin\MyAwesomeProjectWithPocos.xml"

Post-build event to copy the XML file to the same bin folder as the API xml file

  1. SwaggerConfigを変更して、このXMLも含めます

つまり.

_config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "My Api Name");
    c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(GetXmlCommentsPath());
    c.IncludeXmlComments(GetXmlCommentsPathForModels());

}).EnableSwaggerUi(c => { });
_

これで、Swaggerページで、_Model Schema_からModelに切り替えると、モデル全体とプロパティの説明を読み取ることができます。

Click models to see model and property comments

当然、XMLファイルをコピーする必要はありません。ステップ3 GetXmlCommentsPathForModels());で正しい場所を指定するだけでもかまいませんが、これは私のオプションでした。

24
Marcus

あなたが以下の声明を出した場合

c.IncludeXmlComments(GetXmlCommentsPath());

Xmlコメントパスメソッドが、プロジェクトXMLドキュメントファイルが配置されているxmlファイルのパスを返すかどうかを確認できますか？

0
Silly John