Содержание
Remarks: Configuration XML is entirely optional.
This feature allows you to specify annotations that logically apply to either the entire document or to certain set of operations. The configuration XML is handcrafted (NOT generated from Visual Studio built) and follows the format shown below.
<?xml version="1.0"?>
<configuration>
<document>
<variant>
<name>[Your variant name]</name>
<options>
<option security="sg1" version="V2">Group1</option>
<option security="sgnotexist" version="V2">Group2</option>
</options>
</variant>
</document>
<operation>
<annotation tag="Sample V1">
<param name="SampleAddedHeaderParam" required="false" cref="T:System.String" in="header">Added Header Param.</param>
</annotation>
</operation>
</configuration>
You can read the section-by-section guide below.
<document>
This section of the configuration indicates the manner in which the document should be parsed. Currently, there is only one supported child tag.
<variant>
Remarks: Only one variant tag is supported.
This tag indicates that one XML document can be forked into multiple OpenAPI documents, where certain operations will only be present in some documents.
The <name> tag indicates the name of the tag that can be used to mark operations to be included.
The <options> tag lists some of the possible options along with the possible attributes that can be associated with that group of operations. The <options> tag does NOT need to be present for the group name to be used, but simply provides a way to specify the attributes.
For example, parsing the operations below:
/// <summary>
/// Sample Get 1
/// </summary>
/// <group>Sample V1</group>
/// <verb>GET</verb>
/// <url>http://localhost:9000/V1/samples/{id}?queryBool={queryBool}</url>
/// <param name="sampleHeaderParam1" cref="float" in="header">Header param 1</param>
/// <param name="sampleHeaderParam2" cref="string" in="header">Header param 2</param>
/// <param name="sampleHeaderParam3" cref="string" in="header">Header param 3</param>
/// <param name="id" cref="string" in="path">The object id</param>
/// <param name="queryBool" required="true" cref="bool" in="query">Sample query boolean</param>
/// <response code="200"><see cref="SampleObject1"/>Sample object retrieved</response>
/// <response code="400"><see cref="string"/>Bad request</response>
/// <[Your variant name]>Group1</[Your variant name]>
/// <[Your variant name]>Group2</[Your variant name]>
/// <returns>The sample object 1</returns>
[HttpPost]
[Route("/V1/samples/{id}?queryBool={queryBool}")]
public Task<SampleObject1> SampleGet1(string id, bool queryBool)
{
throw new NotSupportedException();
}
/// <summary>
/// Sample Get 2
/// </summary>
/// <group>Sample V1</group>
/// <verb>GET</verb>
/// <url>http://localhost:9000/V1/samples</url>
/// <param name="sampleHeaderParam1" cref="float" in="header">Header param 1</param>
/// <param name="sampleHeaderParam2" cref="string" in="header">Header param 2</param>
/// <param name="sampleHeaderParam3" cref="string" in="header">Header param 3</param>
/// <response code="200"><see cref="SampleObject3"/>Paged Entity contract</response>
/// <response code="400"><see cref="string"/>Bad request</response>
/// <returns>The sample object 3</returns>
[HttpPost]
[Route("/V1/samples")]
public Task<SampleObject3> SampleGet2()
{
throw new NotSupportedException();
}
will yield 3 documents:
- Full document with both operations
- Document for Group1 with only the first operation
- Document for Group2 with only the first operation.
Note that the Group1 and Group2 document variants will also be associated with the security and version attributes as specified in the configuration.
<operation>
This section of the configuration indicates the manner in which each operation should be parsed. Currently, there is only one supported child tag.
<annotation>
This applies all of its children to operations with given tag (or all operations if tag attribute is not present).