APIツールのフレームワークとしてSwaggerを使用していますが、これまでのところうまく機能しています。このページに出会ったばかりです https://petstore.swagger.io/
各メソッドにどのように説明があるかを見ました。例えば、
_POST: pet/
_は_add a new Pet to the store
_で記述されます。 [Description("Description text")]
のようなものを追加する必要があると思いましたが、それはしません。どうすればこれを達成できますか?
これはプロジェクトでよく文書化されています: https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments
生成されたドキュメントをわかりやすい説明で強化するには、コントローラーアクションとモデルに Xml Comments で注釈を付け、出力されたSwagger JSONにこれらのコメントを組み込むようにSwashbuckleを構成します。
1-プロジェクトの[プロパティ]ダイアログを開き、[ビルド]タブをクリックして、[XMLドキュメントファイル]がオンになっていることを確認します。これにより、ビルド時にすべてのXMLコメントを含むファイルが作成されます。
この時点で、XMLコメントが注釈されていないクラスまたはメソッドは、ビルド警告をトリガーします。これを抑制するには、プロパティダイアログの[警告の抑制]フィールドに警告コード「1591」を入力します。
2-生成されたSwagger JSONにファイルのXMLコメントを組み込むようにSwashbuckleを構成します。
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1",
new Info
{
Title = "My API - V1",
Version = "v1"
}
);
var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
c.IncludeXmlComments(filePath);
}
3-要約、注釈、応答タグを使用してアクションに注釈を付けます。
/// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <remarks>Awesomeness!</remarks>
/// <response code="200">Product created</response>
/// <response code="400">Product has missing/invalid values</response>
/// <response code="500">Oops! Can't create your product right now</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(500)]
public Product GetById(int id)
4-サマリータグとサンプルタグでタイプに注釈を付けることもできます。
public class Product
{
/// <summary>
/// The name of the product
/// </summary>
/// <example>Men's basketball shoes</example>
public string Name { get; set; }
/// <summary>
/// Quantity left in stock
/// </summary>
/// <example>10</example>
public int AvailableStock { get; set; }
}
5-プロジェクトをリビルドしてXMLコメントファイルを更新し、Swagger JSONエンドポイントに移動します。説明が対応するSwaggerフィールドにどのようにマッピングされるかに注意してください。
注:APIモデルとそのプロパティにサマリータグを付けて、Swagger Schemaの説明を提供することもできます。複数のXMLコメントファイルがある場合(コントローラーとモデル用の個別のライブラリなど)、IncludeXmlCommentsメソッドを複数回呼び出すことができ、それらはすべて出力Swagger JSONにマージされます
慎重に指示に従うと、次のようなものが表示されます。
https://swashbucklenetcore.azurewebsites.net/swagger/
追加の属性を使用して、必要な詳細をswaggerドキュメントに追加します。
[SwaggerOperationSummary("Add a new Pet to the store")]
[SwaggerImplementationNotes("Adds a new pet using the properties supplied, returns a GUID reference for the pet created.")]
[Route("pets")]
[HttpPost]
public async Task<IHttpActionResult> Post()
{
...
}
そして、設定を変更する際には、これらのフィルターを必ず適用してください。
config.EnableSwagger("swagger",
c =>
{
c.OperationFilter<ApplySwaggerImplementationNotesFilterAttributes>();
c.OperationFilter<ApplySwaggerOperationSummaryFilterAttributes>();
フィルターのコード:
public class ApplySwaggerImplementationNotesFilterAttributes : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
var attr = apiDescription.GetControllerAndActionAttributes<SwaggerImplementationNotesAttribute>().FirstOrDefault();
if (attr != null)
{
operation.description = attr.ImplementationNotes;
}
}
}
public class ApplySwaggerOperationSummaryFilterAttributes : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
var attr = apiDescription.GetControllerAndActionAttributes<SwaggerOperationSummaryAttribute>().FirstOrDefault();
if (attr != null)
{
operation.summary = attr.OperationSummary;
}
}
}
次のように、ドキュメントにコメントを使用できます(標準2ではなく3つのスラッシュ)。
/// <summary>
/// This is method summary I want displayed
/// </summary>
/// <param name="guid">guid as parameter</param>
/// <param name="page_number">Page number - defaults to 0</param>
/// <returns>List of objects returned</returns>