Skip to content

Commit c6f6dc1

Browse files
authored
feat: basic API page output for .NET (#9309)
1 parent 2fccdbd commit c6f6dc1

File tree

201 files changed

+3599
-1270
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

201 files changed

+3599
-1270
lines changed

.editorconfig

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,7 @@ dotnet_diagnostic.IDE0110.severity = suggestion # IDE0110: Remove unnecessary di
162162
dotnet_diagnostic.IDE0240.severity = suggestion # IDE0240: Nullable directive is redundant
163163
dotnet_diagnostic.IDE0241.severity = suggestion # IDE0241: Nullable directive is unnecessary
164164

165+
dotnet_diagnostic.CS8509.severity = suggestion # The switch expression does not handle all possible values of its input type
165166

166167
csharp_style_unused_value_expression_statement_preference = discard_variable:suggestion # IDE0058: Remove unnecessary expression value
167168
csharp_style_unused_value_assignment_preference = discard_variable:suggestion # IDE0059: Remove unnecessary value assignment

Directory.Build.props

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
44
<TargetFrameworks>net6.0;net7.0</TargetFrameworks>
55
<TargetFrameworks Condition=" '$(ContinuousIntegrationBuild)' == 'true' ">$(TargetFrameworks);net8.0</TargetFrameworks>
6-
<LangVersion>Latest</LangVersion>
6+
<LangVersion>Preview</LangVersion>
77
<ImplicitUsings>enable</ImplicitUsings>
88
<InvariantGlobalization>true</InvariantGlobalization>
99
<SuppressNETCoreSdkPreviewMessage>true</SuppressNETCoreSdkPreviewMessage>

Directory.Packages.props

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@
2727
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.7.0" />
2828
<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="1.1.1" />
2929
<PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
30+
<PackageVersion Include="OneOf" Version="3.0.263" />
31+
<PackageVersion Include="OneOf.SourceGenerator" Version="3.0.263" />
3032
<PackageVersion Include="PdfPig" Version="0.1.8" />
3133
<PackageVersion Include="Spectre.Console.Cli" Version="0.47.0" />
3234
<PackageVersion Include="Stubble.Core" Version="1.10.8" />

samples/seed/docfx.json

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,35 @@
4040
"enumSortOrder": "declaringOrder",
4141
"outputFormat": "markdown",
4242
"output": "obj/md"
43+
},
44+
{
45+
"src": [
46+
{
47+
"files": [
48+
"assembly/bin/**/*.dll",
49+
"project/**/*.csproj",
50+
"solution/**/*.sln",
51+
"csharp/**/*.cs",
52+
"vb/**/*.vb"
53+
],
54+
"exclude": [
55+
"project/Project.Core/**"
56+
],
57+
"src": "dotnet"
58+
}
59+
],
60+
"namespaceLayout": "nested",
61+
"enumSortOrder": "declaringOrder",
62+
"outputFormat": "apiPage",
63+
"output": "obj/apipage"
4364
}
4465
],
4566
"build": {
4667
"content": [
4768
{ "files": [ "**/*.yml" ], "src": "obj/api", "dest": "api" },
69+
{ "files": [ "**/*.yml" ], "src": "obj/apipage", "dest": "apipage" },
4870
{ "files": [ "**" ], "src": "obj/md", "dest": "md" },
71+
{ "files": [ "**" ], "src": "obj/apipage", "dest": "apipage" },
4972
{ "files": [ "articles/**/*.{md,yml}", "*.md", "toc.yml", "restapi/**", "md/**", "md2/**" ] }
5073
],
5174
"resource": [

samples/seed/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,7 @@
88
href: obj/api/
99
- name: .NET API (markdown)
1010
href: obj/md/
11+
- name: .NET API (apipage)
12+
href: obj/apipage/
1113
- name: REST API
1214
href: restapi/

templates/modern/schemas/ApiPage.schema.d.ts renamed to schemas/v1.0/ApiPage.d.ts

Lines changed: 23 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,12 @@
11
// Licensed to the .NET Foundation under one or more agreements.
22
// The .NET Foundation licenses this file to you under the MIT license.
33

4-
/**
5-
* This file is used to generate the API page JSON schema. To generate the schema:
6-
* 1. run `npx typescript-json-schema ApiPage.schema.d.ts ApiPage --required --strictNullChecks --out ApiPage.schema.json`
7-
* 2. manually mark properties as markdown
8-
*/
9-
104
/** Define the markdown content type */
115
type markdown = string;
126

137
/** Represents an inline composed of text or links */
14-
type Inline = string | (string | { text: string; url?: string })[];
8+
type Span = string | { text: string; url?: string };
9+
type Inline = Span | Span[];
1510

1611
/** Represents a markdown block */
1712
type Markdown = {
@@ -44,7 +39,7 @@ type Api = (
4439
/** API source URL */
4540
src?: string;
4641

47-
/** Opaque metadata about the API as HTML data-* attributes */
42+
/** Opaque metadata about the API as HTML data-{key} attributes */
4843
metadata?: { [key: string]: string };
4944
};
5045

@@ -71,31 +66,33 @@ type Code = {
7166
/** Code text */
7267
code: string;
7368

74-
/** Code [langauge identifier](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) */
69+
/** Code [language identifier](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) */
7570
languageId?: string;
7671
};
7772

78-
/** Represents a set of parameters */
79-
type Params = {
80-
parameters: {
81-
/** Parameter name */
82-
name?: string;
73+
type Param = {
74+
/** Parameter name */
75+
name?: string;
76+
77+
/** Parameter type */
78+
type?: Inline;
8379

84-
/** Parameter type */
85-
type?: Inline;
80+
/** Parameter default value */
81+
default?: string;
8682

87-
/** Parameter default value */
88-
default?: string;
83+
/** Parameter description in markdown format */
84+
description?: markdown;
8985

90-
/** Parameter description in markdown format */
91-
description?: markdown;
86+
/** Is this parameter deprecated, or the deprecation reason */
87+
deprecated?: boolean | string;
9288

93-
/** Is this parameter deprecated, or the deprecation reason */
94-
deprecated?: boolean | string;
89+
/** Is this parameter optional? */
90+
optional?: boolean;
91+
}
9592

96-
/** Is this parameter optional? */
97-
optional?: boolean;
98-
}[];
93+
/** Represents a set of parameters */
94+
type Params = {
95+
parameters: Param[];
9996
};
10097

10198
/** Represents block level elements */
@@ -114,7 +111,7 @@ type ApiPage = {
114111
/** Page title */
115112
title: string;
116113

117-
/** Opaque metadata about the page as HTML <meta> tags */
114+
/** Opaque metadata about the page as HTML \<meta> tags */
118115
metadata?: { [key: string]: string | string[] };
119116

120117
/** Default code [language identifier](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) */

src/Docfx.Build/ApiPage/ApiPage.cs

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
// Licensed to the .NET Foundation under one or more agreements.
2+
// The .NET Foundation licenses this file to you under the MIT license.
3+
4+
#if NET7_0_OR_GREATER
5+
6+
using System.Text.Json;
7+
using System.Text.Json.Serialization;
8+
using OneOf;
9+
10+
#nullable enable
11+
12+
namespace Docfx.Build.ApiPage;
13+
14+
struct LinkSpan
15+
{
16+
public required string text { get; init; }
17+
public string? url { get; init; }
18+
}
19+
20+
[GenerateOneOf]
21+
partial class Span : OneOfBase<string, LinkSpan> { }
22+
23+
[GenerateOneOf]
24+
partial class Inline : OneOfBase<Span, Span[]> { }
25+
26+
struct Markdown
27+
{
28+
public required string markdown { get; init; }
29+
}
30+
31+
struct H1
32+
{
33+
public required string h1 { get; init; }
34+
public string? id { get; init; }
35+
}
36+
37+
struct H2
38+
{
39+
public required string h2 { get; init; }
40+
public string? id { get; init; }
41+
}
42+
43+
struct H3
44+
{
45+
public required string h3 { get; init; }
46+
public string? id { get; init; }
47+
}
48+
49+
struct H4
50+
{
51+
public required string h4 { get; init; }
52+
public string? id { get; init; }
53+
}
54+
55+
struct H5
56+
{
57+
public required string h5 { get; init; }
58+
public string? id { get; init; }
59+
}
60+
61+
struct H6
62+
{
63+
public required string h6 { get; init; }
64+
public string? id { get; init; }
65+
}
66+
67+
[GenerateOneOf]
68+
partial class Heading : OneOfBase<H1, H2, H3, H4, H5, H6> { }
69+
70+
abstract class ApiBase
71+
{
72+
public string? id { get; init; }
73+
public OneOf<bool, string>? deprecated { get; init; }
74+
public string? src { get; init; }
75+
public Dictionary<string, string>? metadata { get; init; }
76+
}
77+
78+
class Api1 : ApiBase
79+
{
80+
public required string api1 { get; init; }
81+
}
82+
83+
class Api2 : ApiBase
84+
{
85+
public required string api2 { get; init; }
86+
}
87+
88+
class Api3 : ApiBase
89+
{
90+
public required string api3 { get; init; }
91+
}
92+
93+
class Api4 : ApiBase
94+
{
95+
public required string api4 { get; init; }
96+
}
97+
98+
99+
[GenerateOneOf]
100+
partial class Api : OneOfBase<Api1, Api2, Api3, Api4> { }
101+
102+
record struct Fact(string name, Inline value);
103+
104+
struct Facts
105+
{
106+
public required Fact[] facts { get; init; }
107+
}
108+
109+
struct List
110+
{
111+
public required Inline[] list { get; init; }
112+
}
113+
114+
struct Inheritance
115+
{
116+
public required Inline[] inheritance { get; init; }
117+
}
118+
119+
struct Code
120+
{
121+
public required string code { get; init; }
122+
public string? languageId { get; init; }
123+
}
124+
125+
class Parameter
126+
{
127+
public string? name { get; init; }
128+
public Inline? type { get; init; }
129+
public string? @default { get; init; }
130+
public string? description { get; init; }
131+
public OneOf<bool, string>? deprecated { get; init; }
132+
public bool? optional { get; init; }
133+
}
134+
135+
struct Parameters
136+
{
137+
public required Parameter[] parameters { get; init; }
138+
}
139+
140+
[GenerateOneOf]
141+
partial class Block : OneOfBase<Heading, Api, Markdown, Facts, Parameters, List, Inheritance, Code> { }
142+
143+
record ApiPage
144+
{
145+
public static JsonSerializerOptions JsonSerializerOptions { get; } = new()
146+
{
147+
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull | JsonIgnoreCondition.WhenWritingDefault,
148+
};
149+
150+
static ApiPage()
151+
{
152+
JsonSerializerOptions.Converters.Add(new OneOfJsonConverterFactory());
153+
}
154+
155+
public required string title { get; init; }
156+
public required Block[] body { get; init; }
157+
158+
public string? languageId { get; init; }
159+
public Dictionary<string, OneOf<string, string[]>>? metadata { get; init; }
160+
}
161+
162+
#endif

0 commit comments

Comments
 (0)