Docfx: Support OpenAPI v3

[patricksadowski]

DocFX Version Used:
2.35.4

Template used:
default

Steps to Reproduce:

1. Clone docfx-seed
2. Add petstore.yaml to cloned repo inside restapi/
3. Add yamlmime ### YamlMime:ManagedReference in the first line of restapi/petstore.yaml
4. Build with docfx

Expected Behavior:

• Successful build
• Working output with documented REST API
• Use of yaml files as is (without yamlmime)
• Support of OpenAPI v3

Actual Behavior:

Build failed.
[18-05-08 12:55:54.098]Error:System.AggregateException: Mindestens ein Fehler ist aufgetreten. ---> Microsoft.DocAsCode.Build.Engine.Incrementals.BuildCacheException: Full build hasn't loaded model restapi/petstore.yaml
   bei Microsoft.DocAsCode.Build.Engine.HostService.<>c__DisplayClass94_1.<SaveIntermediateModel>b__1()
   bei Microsoft.DocAsCode.Build.Engine.Incrementals.IncrementalUtility.RetryIO(Action action)
   bei System.Threading.Tasks.Parallel.<>c__DisplayClass42_0`2.<PartitionerForEachWorker>b__1()
   bei System.Threading.Tasks.Task.InnerInvokeWithArg(Task childTask)
   bei System.Threading.Tasks.Task.<>c__DisplayClass176_0.<ExecuteSelfReplicating>b__0(Object )
   --- Ende der internen Ausnahmestapelüberwachung ---
   bei System.Threading.Tasks.Task.ThrowIfExceptional(Boolean includeTaskCanceledExceptions)
   bei System.Threading.Tasks.Task.Wait(Int32 millisecondsTimeout, CancellationToken cancellationToken)
   bei System.Threading.Tasks.Parallel.PartitionerForEachWorker[TSource,TLocal](Partitioner`1 source, ParallelOptions parallelOptions, Action`1 simpleBody, Action`2 bodyWithState, Action`3 bodyWithStateAndIndex, Func`4 bodyWithStateAndLocal, Func`5 bodyWithEverything, Func`1 localInit, Action`1 localFinally)
   bei System.Threading.Tasks.Parallel.ForEachWorker[TSource,TLocal](IEnumerable`1 source, ParallelOptions parallelOptions, Action`1 body, Action`2 bodyWithState, Action`3 bodyWithStateAndIndex, Func`4 bodyWithStateAndLocal, Func`5 bodyWithEverything, Func`1 localInit, Action`1 localFinally)
   bei System.Threading.Tasks.Parallel.ForEach[TSource](IEnumerable`1 source, ParallelOptions parallelOptions, Action`1 body)
   bei Microsoft.DocAsCode.Build.Engine.HostService.SaveIntermediateModel(IncrementalBuildContext incrementalContext)
   bei Microsoft.DocAsCode.Build.Engine.CompilePhaseHandlerWithIncremental.PostHandle(List`1 hostServices)
   bei Microsoft.DocAsCode.Build.Engine.PhaseProcessor.Process(List`1 hostServices, Int32 maxParallelism)
   bei Microsoft.DocAsCode.Build.Engine.SingleDocumentBuilder.BuildCore(PhaseProcessor phaseProcessor, List`1 hostServices, DocumentBuildContext context)
   bei Microsoft.DocAsCode.Build.Engine.SingleDocumentBuilder.BuildCore(DocumentBuildParameters parameters)
   bei Microsoft.DocAsCode.Build.Engine.SingleDocumentBuilder.Build(DocumentBuildParameters parameters)
   bei Microsoft.DocAsCode.Build.Engine.DocumentBuilder.BuildCore(DocumentBuildParameters parameter, IMarkdownServiceProvider markdownServiceProvider, BuildInfo currentBuildInfo, BuildInfo lastBuildInfo)
   bei Microsoft.DocAsCode.Build.Engine.DocumentBuilder.Build(IList`1 parameters, String outputDirectory)
   bei Microsoft.DocAsCode.SubCommands.DocumentBuilderWrapper.BuildDocument(BuildJsonConfig config, TemplateManager templateManager, String baseDirectory, String outputDirectory, String pluginDirectory, String templateDirectory)
   bei Microsoft.DocAsCode.SubCommands.BuildCommand.BuildDocument(String baseDirectory, String outputDirectory)
   bei Microsoft.DocAsCode.SubCommands.BuildCommand.Exec(SubCommandRunningContext context)
   bei Microsoft.DocAsCode.SubCommands.CompositeCommand.Exec(SubCommandRunningContext context)
   bei Microsoft.DocAsCode.Program.ExecSubCommand(String[] args)
---> (Interne Ausnahme #0) Microsoft.DocAsCode.Build.Engine.Incrementals.BuildCacheException: Full build hasn't loaded model restapi/petstore.yaml
   bei Microsoft.DocAsCode.Build.Engine.HostService.<>c__DisplayClass94_1.<SaveIntermediateModel>b__1()
   bei Microsoft.DocAsCode.Build.Engine.Incrementals.IncrementalUtility.RetryIO(Action action)
   bei System.Threading.Tasks.Parallel.<>c__DisplayClass42_0`2.<PartitionerForEachWorker>b__1()
   bei System.Threading.Tasks.Task.InnerInvokeWithArg(Task childTask)
   bei System.Threading.Tasks.Task.<>c__DisplayClass176_0.<ExecuteSelfReplicating>b__0(Object )<---

[vwxyzh]

@patricksadowski for Open API 3.0, we use schema driven not manage reference in docs.microsoft.com, but in docfx, we still missing following item:

• integrate CI
• document schema for Open API 3.0
• template for Open API 3.0

Manage reference is only for dotnet API, and we will move to schema driven in v3.

[patricksadowski]

Ok, thank you. I'll be patient and watch https://github.com/dotnet/docfx/projects/1 for updates.

[adanb007]

Does DocFx support OpenAPI 3.0.1 definition by adding the swagger.json. I am getting an error while building my project.

[pryabov]

Good day.
Could you clarify, pls. Do you have any plans to support OpenAPI 3.0.1? And when you are planning to implement this

[adanb007]

If anything, we should know if we need to re-open this issue. The methodology to "downgrade" to the swagger 2.0 definition is not a good solution. Is anyone working on this? maybe on v3?

[superyyrrzz]

OpenAPI v3 is nearly ready on docs.microsoft.com, but there is still no page served.

@adanb007 You are right. v3 uses docs.microsoft.com template, and we need to wait for v3 to ship this feature.

/cc @yishengjin1413

[adanb007]

@superyyrrzz Thanks!

[pryabov]

thank you

[LinasPix]

Any changes on this topic lately?
maybe release date is known or some preview version is available?
Thank you!