daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/web-api/Microsoft.dotnet-openapi.md

120 lines
5.0 KiB
Markdown
Raw Normal View History

Create Microsoft.dotnet-openapi.md (#14450) * Create Microsoft.dotnet-openapi.md * Update toc.yml * Update toc.yml * Update Microsoft.dotnet-openapi.md (#14452) * minor edits
2019-09-22 05:27:17 +08:00
---
title: Develop ASP.NET Core apps using OpenAPI
author: ryanbrandenburg
description: Demonstrates how to use the 'Microsoft.dotnet-openapi' tool to add references to OpenAPI files.
ms.author: rybrande
Link to NuGet package in OpenAPI tool doc (#14647)
2019-09-27 04:28:08 +08:00
ms.date: 09/26/2019
Create Microsoft.dotnet-openapi.md (#14450) * Create Microsoft.dotnet-openapi.md * Update toc.yml * Update toc.yml * Update Microsoft.dotnet-openapi.md (#14452) * minor edits
2019-09-22 05:27:17 +08:00
monikerRange: '>= aspnetcore-3.0'
uid: web-api/Microsoft.dotnet-openapi
---
# Develop ASP.NET Core apps using OpenAPI tools
By Ryan Brandenburg
Link to NuGet package in OpenAPI tool doc (#14647)
2019-09-27 04:28:08 +08:00
[Microsoft.dotnet-openapi](https://www.nuget.org/packages/Microsoft.dotnet-openapi) is a [.NET Core Global Tool](/dotnet/core/tools/global-tools) for managing [OpenAPI](https://github.com/OAI/OpenAPI-Specification) references within a project.
Create Microsoft.dotnet-openapi.md (#14450) * Create Microsoft.dotnet-openapi.md * Update toc.yml * Update toc.yml * Update Microsoft.dotnet-openapi.md (#14452) * minor edits
2019-09-22 05:27:17 +08:00
## Installation
To install `Microsoft.dotnet-openapi`, run the following command:
console --> dotnetcli
2019-09-27 04:03:14 +08:00
```dotnetcli
Create Microsoft.dotnet-openapi.md (#14450) * Create Microsoft.dotnet-openapi.md * Update toc.yml * Update toc.yml * Update Microsoft.dotnet-openapi.md (#14452) * minor edits
2019-09-22 05:27:17 +08:00
dotnet tool install -g Microsoft.dotnet-openapi
```
## Add
Link to NuGet package in OpenAPI tool doc (#14647)
2019-09-27 04:28:08 +08:00
Adding an OpenAPI reference using any of the commands on this page adds an `<OpenApiReference />` element similar to the following to the *.csproj* file:
Create Microsoft.dotnet-openapi.md (#14450) * Create Microsoft.dotnet-openapi.md * Update toc.yml * Update toc.yml * Update Microsoft.dotnet-openapi.md (#14452) * minor edits
2019-09-22 05:27:17 +08:00
```xml
<OpenApiReference Include="openapi.json" />
```
The preceding reference is required for the app to call the generated client code.
<!-- TODO: Restore after https://github.com/aspnet/AspNetCore/issues/12738
### Add Project
#### Options
| Short option | Long option | Description | Example |
|-------|------|-------|---------|
| -v|--verbose | Show verbose output. |dotnet openapi add project *-v* ../Ref/ProjRef.csproj |
| -p|--project | The project to operate on. |dotnet openapi add project *--project .\Ref.csproj* ../Ref/ProjRef.csproj |
#### Arguments
| Argument | Description | Example |
|-------------|-------------|---------|
| source-file | The source to create a reference from. Must be a project file. |dotnet openapi add project *../Ref/ProjRef.csproj* | -->
### Add File
#### Options
| Short option| Long option| Description | Example |
|-------|------|-------|---------|
| -v|--verbose | Show verbose output. |dotnet openapi add file *-v* .\OpenAPI.json |
| -p|--updateProject | The project to operate on. |dotnet openapi add file *--updateProject .\Ref.csproj* .\OpenAPI.json |
| -c|--code-generator| The code generator to apply to the reference. Options are `NSwagCSharp` and `NSwagTypeScript`. If `--code-generator` is not specified the tooling defaults to `NSwagCSharp`.|dotnet openapi add file .\OpenApi.json --code-generator
| -h|--help|Show help information|dotnet openapi add file --help|
#### Arguments
| Argument | Description | Example |
|-------------|-------------|---------|
| source-file | The source to create a reference from. Must be an OpenAPI file. |dotnet openapi add file *.\OpenAPI.json* |
### Add URL
#### Options
| Short option| Long option| Description | Example |
|-------|------|-------------|---------|
| -v|--verbose | Show verbose output. |dotnet openapi add url *-v* `https://contoso.com/openapi.json` |
| -p|--updateProject | The project to operate on. |dotnet openapi add url *--updateProject .\Ref.csproj* `https://contoso.com/openapi.json` |
| -o|--output-file | Where to place the local copy of the OpenAPI file. |dotnet openapi add url `https://contoso.com/openapi.json` *--output-file myclient.json* |
| -c|--code-generator| The code generator to apply to the reference. Options are `NSwagCSharp` and `NSwagTypeScript`. |dotnet openapi add file .\OpenApi.json --code-generator
| -h|--help|Show help information|dotnet openapi add url --help|
#### Arguments
| Argument | Description | Example |
|-------------|-------------|---------|
| source-URL | The source to create a reference from. Must be a URL. |dotnet openapi add url `https://contoso.com/openapi.json` |
## Remove
Removes the OpenAPI reference matching the given filename from the *.csproj* file. When the OpenAPI reference is removed, clients won't be generated. Local *.json* and *.yaml* files are deleted.
### Options
| Short option| Long option| Description| Example |
|-------|------|------------|---------|
| -v|--verbose | Show verbose output. |dotnet openapi remove *-v*|
| -p|--updateProject | The project to operate on. |dotnet openapi remove *--updateProject .\Ref.csproj* .\OpenAPI.json |
| -h|--help|Show help information|dotnet openapi remove --help|
### Arguments
| Argument | Description| Example |
| ------------|------------|---------|
| source-file | The source to remove the reference to. |dotnet openapi remove *.\OpenAPI.json* |
## Refresh
Refreshes the local version of a file that was downloaded using the latest content from the download URL.
### Options
| Short option| Long option| Description | Example |
|-------|------|-------------|---------|
| -v|--verbose | Show verbose output. | dotnet openapi refresh *-v* `https://contoso.com/openapi.json` |
| -p|--updateProject | The project to operate on. | dotnet openapi refresh *--updateProject .\Ref.csproj* `https://contoso.com/openapi.json` |
| -h|--help|Show help information|dotnet openapi refresh --help|
### Arguments
| Argument | Description | Example |
| ------------|-------------|---------|
| source-URL | The URL to refresh the reference from. | dotnet openapi refresh `https://contoso.com/openapi.json` |