Microsoft Xml 3.0 Mac
Vulnerability in XML Core Services Could Allow Remote Code Execution (2993958)
Published: November 11, 2014
Version: 1.0
Executive Summary
Open XML Converter allows you to convert Open XML files that were created in Office 2008 for Mac or Office 2007 for Windows so that you can open, edit, and save them in earlier versions of Office for Mac. MSXML 3.0 and MSXML 6.0 Windows Server 2008 for Itanium-based Systems and Windows Server 2008 for Itanium-based Systems SP2 973688 Description of an update for Microsoft XML.
This security update resolves a privately reported vulnerability in Microsoft Windows. The vulnerability could allow remote code execution if a logged-on user visits a specially crafted website that is designed to invoke Microsoft XML Core Services (MSXML) through Internet Explorer. In all cases, however, an attacker would have no way to force users to visit such websites. Instead, an attacker would have to convince users to visit a website, typically by getting them to click a link in an email message or in an Instant Messenger request that takes users to the attacker's website.
This security update for Microsoft XML Core Services 3.0 is rated Critical for affected releases of Microsoft Windows clients and Important for affected releases of Microsoft Windows servers. For more information, see the Affected Software section.
The security update addresses the vulnerability by modifying the way that Microsoft XML Core Services parses XML content. For more information about the vulnerability, see the Frequently Asked Questions (FAQ) subsection for the specific vulnerability.
For more information about this document, see Knowledge Base Article 2993958.
Affected Software
The following software versions or editions are affected. Versions or editions that are not listed are either past their support life cycle or are not affected. To determine the support life cycle for your software version or edition, see Microsoft Support Lifecycle.
| **Operating System** | **Component** | **Maximum Security Impact** | **Aggregate Severity Rating** | **Updates Replaced** |
| **Windows Server 2003** | ||||
| [Windows Server 2003 Service Pack 2](https://www.microsoft.com/download/details.aspx?familyid=9c155ddf-81ad-45e7-a32a-6c0d63d3cdb0) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| [Windows Server 2003 x64 Edition Service Pack 2](https://www.microsoft.com/download/details.aspx?familyid=dd2608d4-360e-4ac8-a40d-ffbb6787ce36) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| [Windows Server 2003 with SP2 for Itanium-based Systems](https://www.microsoft.com/download/details.aspx?familyid=d36dcc62-7d65-42ab-a088-9f339a78b931) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| **Windows Vista** | ||||
| [Windows Vista Service Pack 2](https://www.microsoft.com/download/details.aspx?familyid=5381ce98-0888-4670-9e4a-b2773ec2f105) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| [Windows Vista x64 Edition Service Pack 2](https://www.microsoft.com/download/details.aspx?familyid=06837728-7aa9-4d77-a656-06fe9dd10911) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| **Windows Server 2008** | ||||
| [Windows Server 2008 for 32-bit Systems Service Pack 2](https://www.microsoft.com/download/details.aspx?familyid=22fa4d32-dcf2-46ab-b9d9-97b10639ef80) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| [Windows Server 2008 for x64-based Systems Service Pack 2](https://www.microsoft.com/download/details.aspx?familyid=3c82b219-6259-4457-914a-a6500733033d) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| [Windows Server 2008 for Itanium-based Systems Service Pack 2](https://www.microsoft.com/download/details.aspx?familyid=599f3cdd-0269-4f8a-bb03-24ffe9bb5153) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| **Windows 7** | ||||
| [Windows 7 for 32-bit Systems Service Pack 1](https://www.microsoft.com/download/details.aspx?familyid=d5b096b7-0bd8-4598-9a79-91ba08a98b6c) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| [Windows 7 for x64-based Systems Service Pack 1](https://www.microsoft.com/download/details.aspx?familyid=93e180a1-b7b9-4153-8ab1-d536494d9263) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| **Windows Server 2008 R2** | ||||
| [Windows Server 2008 R2 for x64-based Systems Service Pack 1](https://www.microsoft.com/download/details.aspx?familyid=0a1b546f-5817-4f88-8c9d-3175e970f189) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| [Windows Server 2008 R2 for Itanium-based Systems Service Pack 1](https://www.microsoft.com/download/details.aspx?familyid=7c8882e7-80c3-4453-8768-0a910d6576dd) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| **Windows 8 and Windows 8.1** | ||||
| [Windows 8 for 32-bit Systems](https://www.microsoft.com/download/details.aspx?familyid=e7e5d876-4fac-4121-84af-a61772252aa3) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| [Windows 8 for x64-based Systems](https://www.microsoft.com/download/details.aspx?familyid=f2af12e6-5dc2-43c2-b184-dae8b71bdc76) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| [Windows 8.1 for 32-bit Systems](https://www.microsoft.com/download/details.aspx?familyid=c08ab9f1-a9b6-4898-8ddc-62dbf43ccf21) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| [Windows 8.1 for x64-based Systems](https://www.microsoft.com/download/details.aspx?familyid=d1d77ff5-4a70-4384-b513-cdb692edfe2d) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| **Windows Server 2012 and Windows Server 2012 R2** | ||||
| [Windows Server 2012](https://www.microsoft.com/download/details.aspx?familyid=da6f84a2-9262-43fa-b01a-b1dd4cc750ce) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| [Windows Server 2012 R2](https://www.microsoft.com/download/details.aspx?familyid=a3a7a5a1-b390-44aa-9c92-5208fe570d58) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| **Windows RT and Windows RT 8.1** | ||||
| Windows RT[1](2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| Windows RT 8.1[1](2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Critical | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| **Server Core installation option** | ||||
| [Windows Server 2008 for 32-bit Systems Service Pack 2](https://www.microsoft.com/download/details.aspx?familyid=22fa4d32-dcf2-46ab-b9d9-97b10639ef80) (Server Core installation) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| [Windows Server 2008 for x64-based Systems Service Pack 2](https://www.microsoft.com/download/details.aspx?familyid=3c82b219-6259-4457-914a-a6500733033d) (Server Core installation) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| [Windows Server 2008 R2 for x64-based Systems Service Pack 1](https://www.microsoft.com/download/details.aspx?familyid=0a1b546f-5817-4f88-8c9d-3175e970f189) (Server Core installation) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2916036 in [MS14-005](http://go.microsoft.com/fwlink/?linkid=391022) |
| [Windows Server 2012](https://www.microsoft.com/download/details.aspx?familyid=da6f84a2-9262-43fa-b01a-b1dd4cc750ce) (Server Core installation) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
| [Windows Server 2012 R2](https://www.microsoft.com/download/details.aspx?familyid=a3a7a5a1-b390-44aa-9c92-5208fe570d58) (Server Core installation) (2993958) | Microsoft XML Core Services 3.0 | Remote Code Execution | Important | 2939576 in [MS14-033](http://go.microsoft.com/fwlink/?linkid=398119) |
Note Windows Technical Preview and Windows Server Technical Preview are affected. Customers running these operating systems are encouraged to apply the update, which is available via Windows Update.
Update FAQ
What version of Microsoft XML Core Services is installed on my system?
Some versions of Microsoft XML Core Services are included with Microsoft Windows; others are installed with non-operating system software from Microsoft or third-party providers. Some are also available as separate downloads. The following table shows the supported releases of Microsoft Windows and indicates which versions of Microsoft XML Core Services are included with the operating system, and which versions are installed when you install additional Microsoft or third-party software.
| Operating System | MSXML 3.0 and MSXML 6.0 | MSXML 4.0 and MSXML 5.0 |
| Windows Server 2003 | MSXML 3.0 shipped with operating system. MSXML 6.0 installed with additional software. | Installed with additional software |
| Windows Vista | Shipped with operating system | Installed with additional software |
| Windows Server 2008 | Shipped with operating system | Installed with additional software |
| Windows 7 | Shipped with operating system | Installed with additional software |
| Windows Server 2008 R2 | Shipped with operating system | Installed with additional software |
| Windows 8 | Shipped with operating system | Installed with additional software |
| Windows Server 2012 | Shipped with operating system | Installed with additional software |
| Windows RT | Shipped with operating system | MSXML 4.0 installed with additional software. MSXML 5.0 not applicable. |
| Windows 8.1 | Shipped with operating system | Installed with additional software |
| Windows Server 2012 R2 | Shipped with operating system | Installed with additional software |
| Windows RT 8.1 | Shipped with operating system | MSXML 4.0 installed with additional software. MSXML 5.0 not applicable. |
| **Vulnerability Severity Rating and Maximum Security Impact by Affected Software** | ||
| **Affected Software** | [**MSXML Remote Code Execution Vulnerability - CVE-2014-4118**](http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=cve-2014-4118) | **Aggregate Severity Rating** |
| **Windows Server 2003** | ||
| Windows Server 2003 Service Pack 2 (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2003 x64 Edition Service Pack 2 (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2003 with SP2 for Itanium-based Systems (2993958) | **Important** Remote Code Execution | **Important** |
| **Windows Vista** | ||
| Windows Vista Service Pack 2 (2993958) | **Critical** Remote Code Execution | **Critical** |
| Windows Vista x64 Edition Service Pack 2 (2993958) | **Critical** Remote Code Execution | **Critical** |
| **Windows Server 2008** | ||
| Windows Server 2008 for 32-bit Systems Service Pack 2 (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2008 for x64-based Systems Service Pack 2 (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2008 for Itanium-based Systems Service Pack 2 (2993958) | **Important** Remote Code Execution | **Important** |
| **Windows 7** | ||
| Windows 7 for 32-bit Systems Service Pack 1 (2993958) | **Critical** Remote Code Execution | **Critical** |
| Windows 7 for x64-based Systems Service Pack 1 (2993958) | **Critical** Remote Code Execution | **Critical** |
| **Windows Server 2008 R2** | ||
| Windows Server 2008 R2 for x64-based Systems Service Pack 1 (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2008 R2 for Itanium-based Systems Service Pack 1 (2993958) | **Important** Remote Code Execution | **Important** |
| **Windows 8 and Windows 8.1** | ||
| Windows 8 for 32-bit Systems (2993958) | **Critical** Remote Code Execution | **Critical** |
| Windows 8 for x64-based Systems (2993958) | **Critical** Remote Code Execution | **Critical** |
| Windows 8.1 for 32-bit Systems (2993958) | **Critical** Remote Code Execution | **Critical** |
| Windows 8.1 for x64-based Systems (2993958) | **Critical** Remote Code Execution | **Critical** |
| **Windows Server 2012 and Windows Server 2012 R2** | ||
| Windows Server 2012 (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2012 R2 (2993958) | **Important** Remote Code Execution | **Important** |
| **Windows RT and Windows RT 8.1** | ||
| Windows RT (2993958) | **Critical** Remote Code Execution | **Critical** |
| Windows RT 8.1 (2993958) | **Critical** Remote Code Execution | **Critical** |
| **Server Core installation option** | ||
| Windows Server 2008 for 32-bit Systems Service Pack 2 (Server Core installation) (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2008 for x64-based Systems Service Pack 2 (Server Core installation) (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2008 R2 for x64-based Systems Service Pack 1 (Server Core installation) (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2012 (Server Core installation) (2993958) | **Important** Remote Code Execution | **Important** |
| Windows Server 2012 R2 (Server Core installation) (2993958) | **Important** Remote Code Execution | **Important** |
MSXML Remote Code Execution Vulnerability - CVE-2014-4118
A remote code execution vulnerability exists when Microsoft XML Core Services (MSXML) improperly parses XML content, which can corrupt the system state in such a way as to allow an attacker to run arbitrary code. The vulnerability could allow remote code execution if a user opens a specially crafted file or webpage. Microsoft received information about this vulnerability through coordinated vulnerability disclosure. When this security bulletin was issued, Microsoft had not received any information to indicate that this vulnerability had been publicly used to attack customers. The update addresses the vulnerability by modifying the way that Microsoft XML Core Services parses XML content.
Mitigating Factors
The following mitigating factors may be helpful in your situation:
- In a web-based attack scenario, an attacker could host a specially crafted website that is designed to exploit MSXML through Internet Explorer, and then convince a user to view the website. This could also include compromised websites and websites that accept or host user-provided content or advertisements. These websites could contain specially crafted content that could exploit this vulnerability. In all cases, however, an attacker would have no way to force users to view the attacker-controlled content. Instead, an attacker would have to convince users to take action, typically by getting them to click a link in an email message or in an Instant Messenger request that takes users to the attacker's website, or by getting them to open an attachment sent through email.
- An attacker who successfully exploited this vulnerability could gain the same user rights as the current user. Customers whose accounts are configured to have fewer user rights on the system could be less impacted than those who operate with administrative user rights.
- By default, all supported versions of Microsoft Outlook, Microsoft Outlook Express, and Windows Mail open HTML email messages in the Restricted sites zone. The Restricted sites zone, which disables script and ActiveX controls, helps reduce the risk of an attacker being able to use this vulnerability to execute malicious code. If a user clicks a link in an email message, the user could still be vulnerable to exploitation of this vulnerability through the web-based attack scenario.
- By default, Internet Explorer on Windows Server 2003, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, and Windows Server 2012 R2 runs in a restricted mode that is known as Enhanced Security Configuration. This mode mitigates this vulnerability. See the FAQ section for this vulnerability for more information about Internet Explorer Enhanced Security Configuration.
Workarounds
Microsoft has tested the following workarounds and states in the discussion whether a workaround reduces functionality:
Prevent MSXML 3.0 binary behaviors from being used in Internet Explorer
You can disable attempts to use a specific binary behavior in Internet Explorer by setting the kill bit for the behavior in the registry.Warning If you use Registry Editor incorrectly, you may cause serious problems that may require you to reinstall your operating system. Microsoft cannot guarantee that you can solve problems that result from using Registry Editor incorrectly. Use Registry Editor at your own risk.
To set the kill bits for CLSIDs with value of {f5078f39-c551-11d3-89b9-0000f81fe221} and {f6d90f16-9c73-11d3-b32e-00c04f990bb4}, paste the following text in a text editor such as Notepad. Then, save the file by using the .reg file name extension.
You can apply this .reg file to individual systems by double-clicking it. You can also apply it across domains by using Group Policy. For more information about Group Policy, see the TechNet article, Group Policy Collection.
| Note: |
|---|
| You must restart Internet Explorer for your changes to take effect. |
Impact of workaround. Websites that use the XMLHTTP 3.0 ActiveX controls may no longer display or function correctly in Internet Explorer.
How to undo the workaround. Delete the registry keys previously added in implementing this workaround.
FAQ
What is the component affected by the vulnerability?
The vulnerability affects Microsoft XML Core Services (MSXML), which allows customers who use JScript, Visual Basic Scripting Edition (VBScript), and Microsoft Visual Studio 6.0 to develop XML-based applications that provide interoperability with other applications that adhere to the XML 1.0 standard. For more information, see the Microsoft Developer Network article, MSXML.
What might an attacker use the vulnerability to do?
An attacker who successfully exploited this vulnerability could gain the same user rights as the logged-on user. If a user is logged on with administrative user rights, an attacker could then install programs; view, change, or delete data; or create new accounts with full user rights. Users whose accounts are configured to have fewer user rights on the system could be less impacted than users who operate with administrative user rights.
How could an attacker exploit the vulnerability?
An attacker could exploit the vulnerability by hosting a specially crafted website that is designed to invoke MSXML through Internet Explorer. This can also include compromised websites and websites that accept or host user-provided content or advertisements. These websites could contain specially crafted content that could exploit this vulnerability. In all cases, however, an attacker would have no way to force users to visit these websites. Instead, an attacker would have to convince users to visit the website, typically by getting them to click a link in an email message or in an Instant Messenger request that takes users to the attacker's website. It could also be possible to display specially crafted web content by using banner advertisements or by using other methods to deliver web content to affected systems.
Non-Microsoft web applications and services that utilize the MSXML library for parsing XML could also be vulnerable to this attack.
What systems are primarily at risk from the vulnerability?
Greek letters microsoft word mac. This vulnerability requires that a user be logged on and visiting a website for any malicious action to occur. Therefore, any systems where Internet Explorer is used frequently, such as workstations or terminal servers, are at the most risk from this vulnerability.
I am running Internet Explorer on Windows Server 2003, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, or Windows Server 2012 R2. Does this mitigate this vulnerability?
Yes. By default, Internet Explorer on Windows Server 2003, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, and Windows Server 2012 R2 runs in a restricted mode that is known as Enhanced Security Configuration. Enhanced Security Configuration is a group of preconfigured settings in Internet Explorer that can reduce the likelihood of a user or administrator downloading and running specially crafted web content on a server. This is a mitigating factor for websites that you have not added to the Internet Explorer Trusted sites zone.
Security Update Deployment
For Security Update Deployment information, see the Microsoft Knowledge Base article referenced in the Executive Summary.
Acknowledgments
Microsoft recognizes the efforts of those in the security community who help us protect customers through coordinated vulnerability disclosure. See Acknowledgments for more information.
Disclaimer
The information provided in the Microsoft Knowledge Base is provided 'as is' without warranty of any kind. Microsoft disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. In no event shall Microsoft Corporation or its suppliers be liable for any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits or special damages, even if Microsoft Corporation or its suppliers have been advised of the possibility of such damages. Some states do not allow the exclusion or limitation of liability for consequential or incidental damages so the foregoing limitation may not apply.
Revisions
- V1.0 (November 11, 2014): Bulletin published.
Page generated 2015-01-14 11:39Z-08:00.
-->By Shayne Boyer and Scott Addie
View or download sample code (how to download)
There are three main components to Swashbuckle:
Swashbuckle.AspNetCore.Swagger: a Swagger object model and middleware to expose
SwaggerDocumentobjects as JSON endpoints.Swashbuckle.AspNetCore.SwaggerGen: a Swagger generator that builds
SwaggerDocumentobjects directly from your routes, controllers, and models. It's typically combined with the Swagger endpoint middleware to automatically expose Swagger JSON.Swashbuckle.AspNetCore.SwaggerUI: an embedded version of the Swagger UI tool. It interprets Swagger JSON to build a rich, customizable experience for describing the web API functionality. It includes built-in test harnesses for the public methods.
Package installation
Microsoft Xml Viewer
Swashbuckle can be added with the following approaches:
From the Package Manager Console window:
Go to View > Other Windows > Package Manager Console
Navigate to the directory in which the TodoApi.csproj file exists
Execute the following command:
From the Manage NuGet Packages dialog:
- Right-click the project in Solution Explorer > Manage NuGet Packages
- Set the Package source to 'nuget.org'
- Ensure the 'Include prerelease' option is enabled
- Enter 'Swashbuckle.AspNetCore' in the search box
- Select the latest 'Swashbuckle.AspNetCore' package from the Browse tab and click Install
- Right-click the Packages folder in Solution Pad > Add Packages..
- Set the Add Packages window's Source drop-down to 'nuget.org'
- Ensure the 'Show pre-release packages' option is enabled
- Enter 'Swashbuckle.AspNetCore' in the search box
- Select the latest 'Swashbuckle.AspNetCore' package from the results pane and click Add Package
Run the following command from the Integrated Terminal:
Run the following command:
Add and configure Swagger middleware
In the Startup class, import the following namespace to use the OpenApiInfo class:
Add the Swagger generator to the services collection in the Startup.ConfigureServices method:
In the Startup.Configure method, enable the middleware for serving the generated JSON document and the Swagger UI:
The preceding UseSwaggerUI method call enables the Static File Middleware. If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project.
Launch the app, and navigate to http://localhost:<port>/swagger/v1/swagger.json. The generated document describing the endpoints appears as shown in Swagger specification (swagger.json).
The Swagger UI can be found at http://localhost:<port>/swagger. Explore the API via Swagger UI and incorporate it in other programs.
Tip
To serve the Swagger UI at the app's root (http://localhost:<port>/), set the RoutePrefix property to an empty string:
If using directories with IIS or a reverse proxy, set the Swagger endpoint to a relative path using the ./ prefix. For example, ./swagger/v1/swagger.json. Using /swagger/v1/swagger.json instructs the app to look for the JSON file at the true root of the URL (plus the route prefix, if used). For example, use http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json instead of http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.
Customize and extend
Swagger provides options for documenting the object model and customizing the UI to match your theme.
In the Startup class, add the following namespaces:
API info and description
The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and description:
The Swagger UI displays the version's information:
XML comments
XML comments can be enabled with the following approaches:
- Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
- Manually add the highlighted lines to the .csproj file:
- Right-click the project in Solution Explorer and select Properties.
- Check the XML documentation file box under the Output section of the Build tab.
- From the Solution Pad, press control and click the project name. Navigate to Tools > Edit File.
- Manually add the highlighted lines to the .csproj file:
- Open the Project Options dialog > Build > Compiler
- Check the Generate xml documentation box under the General Options section
Manually add the highlighted lines to the .csproj file:
Manually add the highlighted lines to the .csproj file:
Enabling XML comments provides debug information for undocumented public types and members. Undocumented types and members are indicated by the warning message. For example, the following message indicates a violation of warning code 1591:
To suppress warnings project-wide, define a semicolon-delimited list of warning codes to ignore in the project file. Appending the warning codes to $(NoWarn); applies the C# default values too.
To suppress warnings only for specific members, enclose the code in #pragma warning preprocessor directives. This approach is useful for code that shouldn't be exposed via the API docs. In the following example, warning code CS1591 is ignored for the entire Program class. Enforcement of the warning code is restored at the close of the class definition. Specify multiple warning codes with a comma-delimited list.
Configure Swagger to use the XML file that's generated with the preceding instructions. For Linux or non-Windows operating systems, file names and paths can be case-sensitive. For example, a TodoApi.XML file is valid on Windows but not CentOS.
In the preceding code, Reflection is used to build an XML file name matching that of the web API project. The AppContext.BaseDirectory property is used to construct a path to the XML file. Some Swagger features (for example, schemata of input parameters or HTTP methods and response codes from the respective attributes) work without the use of an XML documentation file. For most features, namely method summaries and the descriptions of parameters and response codes, the use of an XML file is mandatory.
Adding triple-slash comments to an action enhances the Swagger UI by adding the description to the section header. Add a <summary> element above the Delete action:
The Swagger UI displays the inner text of the preceding code's <summary> element:
The UI is driven by the generated JSON schema:
Add a <remarks> element to the Create action method documentation. It supplements information specified in the <summary> element and provides a more robust Swagger UI. The <remarks> element content can consist of text, JSON, or XML.
Notice the UI enhancements with these additional comments:
Data annotations
Mark the model with attributes, found in the System.ComponentModel.DataAnnotations namespace, to help drive the Swagger UI components.
Add the [Required] attribute to the Name property of the TodoItem class:
The presence of this attribute changes the UI behavior and alters the underlying JSON schema:
Add the [Produces('application/json')] attribute to the API controller. Its purpose is to declare that the controller's actions support a response content type of application/json:
The Response Content Type drop-down selects this content type as the default for the controller's GET actions:
As the usage of data annotations in the web API increases, the UI and API help pages become more descriptive and useful.
Microsoft Xml 3.0 Mac Pro
Describe response types
Developers consuming a web API are most concerned with what's returned—specifically response types and error codes (if not standard). The response types and error codes are denoted in the XML comments and data annotations.
The Create action returns an HTTP 201 status code on success. An HTTP 400 status code is returned when the posted request body is null. Without proper documentation in the Swagger UI, the consumer lacks knowledge of these expected outcomes. Fix that problem by adding the highlighted lines in the following example:
The Swagger UI now clearly documents the expected HTTP response codes:
In ASP.NET Core 2.2 or later, conventions can be used as an alternative to explicitly decorating individual actions with [ProducesResponseType]. For more information, see Use web API conventions.
Customize the UI
The stock UI is both functional and presentable. However, API documentation pages should represent your brand or theme. Branding the Swashbuckle components requires adding the resources to serve static files and building the folder structure to host those files.
If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project:
The preceding NuGet package is already installed if targeting .NET Core 2.x and using the metapackage.
Microsoft Core Xml
Enable Static File Middleware:
Acquire the contents of the dist folder from the Swagger UI GitHub repository. This folder contains the necessary assets for the Swagger UI page.
Create a wwwroot/swagger/ui folder, and copy into it the contents of the dist folder.
Create a custom.css file, in wwwroot/swagger/ui, with the following CSS to customize the page header:
Reference custom.css in the index.html file inside ui folder, after any other CSS files:
Browse to the index.html page at http://localhost:<port>/swagger/ui/index.html. Enter https://localhost:<port>/swagger/v1/swagger.json in the header's textbox, and click the Explore button. The resulting page looks as follows:
Microsoft Xml 3.0 Mac Torrent
There's much more you can do with the page. See the full capabilities for the UI resources at the Swagger UI GitHub repository.