Skip to content

Commit 37e51cd

Browse files
mtojekmtojek
committed
Markdown template
1 parent eef09e6 commit 37e51cd

27 files changed

+807
-16
lines changed

‎docs/api.md

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
1-
<!-- Generator: Widdershins v4.0.1 -->
21

32
<h1 id="coderd-api">Coderd API v2.0</h1>
43

5-
> Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
4+
> XScroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
65
76
Coderd is the service created by running coder server. It is a thin API that connects workspaces, provisioners and users. coderd stores its state in Postgres and is the only service that communicates with Postgres.
87

@@ -369,7 +368,7 @@ CoderSessionToken
369368
# Schemas
370369

371370
<h2 id="tocS_codersdk.DERPRegion">codersdk.DERPRegion</h2>
372-
<!-- backwards compatibility -->
371+
373372
<a id="schemacodersdk.derpregion"></a>
374373
<a id="schema_codersdk.DERPRegion"></a>
375374
<a id="tocScodersdk.derpregion"></a>
@@ -391,7 +390,7 @@ CoderSessionToken
391390
|preferred|boolean|false|none|none|
392391

393392
<h2 id="tocS_codersdk.Healthcheck">codersdk.Healthcheck</h2>
394-
<!-- backwards compatibility -->
393+
395394
<a id="schemacodersdk.healthcheck"></a>
396395
<a id="schema_codersdk.Healthcheck"></a>
397396
<a id="tocScodersdk.healthcheck"></a>
@@ -415,7 +414,7 @@ CoderSessionToken
415414
|url|string|false|none|URL specifies the url to check for the app health.|
416415

417416
<h2 id="tocS_codersdk.NullTime">codersdk.NullTime</h2>
418-
<!-- backwards compatibility -->
417+
419418
<a id="schemacodersdk.nulltime"></a>
420419
<a id="schema_codersdk.NullTime"></a>
421420
<a id="tocScodersdk.nulltime"></a>
@@ -437,7 +436,7 @@ CoderSessionToken
437436
|valid|boolean|false|none|Valid is true if Time is not NULL|
438437

439438
<h2 id="tocS_codersdk.ProvisionerJob">codersdk.ProvisionerJob</h2>
440-
<!-- backwards compatibility -->
439+
441440
<a id="schemacodersdk.provisionerjob"></a>
442441
<a id="schema_codersdk.ProvisionerJob"></a>
443442
<a id="tocScodersdk.provisionerjob"></a>
@@ -479,7 +478,7 @@ CoderSessionToken
479478
|worker_id|string|false|none|none|
480479

481480
<h2 id="tocS_codersdk.Response">codersdk.Response</h2>
482-
<!-- backwards compatibility -->
481+
483482
<a id="schemacodersdk.response"></a>
484483
<a id="schema_codersdk.Response"></a>
485484
<a id="tocScodersdk.response"></a>
@@ -508,7 +507,7 @@ CoderSessionToken
508507
|validations|[[codersdk.ValidationError](#schemacodersdk.validationerror)]|false|none|Validations are form field-specific friendly error messages. They will be<br>shown on a form field in the UI. These can also be used to add additional<br>context if there is a set of errors in the primary 'Message'.|
509508

510509
<h2 id="tocS_codersdk.ValidationError">codersdk.ValidationError</h2>
511-
<!-- backwards compatibility -->
510+
512511
<a id="schemacodersdk.validationerror"></a>
513512
<a id="schema_codersdk.ValidationError"></a>
514513
<a id="tocScodersdk.validationerror"></a>
@@ -530,7 +529,7 @@ CoderSessionToken
530529
|field|string|true|none|none|
531530

532531
<h2 id="tocS_codersdk.Workspace">codersdk.Workspace</h2>
533-
<!-- backwards compatibility -->
532+
534533
<a id="schemacodersdk.workspace"></a>
535534
<a id="schema_codersdk.Workspace"></a>
536535
<a id="tocScodersdk.workspace"></a>
@@ -688,7 +687,7 @@ CoderSessionToken
688687
|updated_at|string|false|none|none|
689688

690689
<h2 id="tocS_codersdk.WorkspaceAgent">codersdk.WorkspaceAgent</h2>
691-
<!-- backwards compatibility -->
690+
692691
<a id="schemacodersdk.workspaceagent"></a>
693692
<a id="schema_codersdk.WorkspaceAgent"></a>
694693
<a id="tocScodersdk.workspaceagent"></a>
@@ -776,7 +775,7 @@ CoderSessionToken
776775
|version|string|false|none|none|
777776

778777
<h2 id="tocS_codersdk.WorkspaceApp">codersdk.WorkspaceApp</h2>
779-
<!-- backwards compatibility -->
778+
780779
<a id="schemacodersdk.workspaceapp"></a>
781780
<a id="schema_codersdk.WorkspaceApp"></a>
782781
<a id="tocScodersdk.workspaceapp"></a>
@@ -816,7 +815,7 @@ CoderSessionToken
816815
|subdomain|boolean|false|none|Subdomain denotes whether the app should be accessed via a path on the<br>`coder server` or via a hostname-based dev URL. If this is set to true<br>and there is no app wildcard configured on the server, the app will not<br>be accessible in the UI.|
817816

818817
<h2 id="tocS_codersdk.WorkspaceBuild">codersdk.WorkspaceBuild</h2>
819-
<!-- backwards compatibility -->
818+
820819
<a id="schemacodersdk.workspacebuild"></a>
821820
<a id="schema_codersdk.WorkspaceBuild"></a>
822821
<a id="tocScodersdk.workspacebuild"></a>
@@ -960,7 +959,7 @@ CoderSessionToken
960959
|workspace_owner_name|string|false|none|none|
961960

962961
<h2 id="tocS_codersdk.WorkspaceResource">codersdk.WorkspaceResource</h2>
963-
<!-- backwards compatibility -->
962+
964963
<a id="schemacodersdk.workspaceresource"></a>
965964
<a id="schema_codersdk.WorkspaceResource"></a>
966965
<a id="tocScodersdk.workspaceresource"></a>
@@ -1057,7 +1056,7 @@ CoderSessionToken
10571056
|workspace_transition|string|false|none|none|
10581057

10591058
<h2 id="tocS_codersdk.WorkspaceResourceMetadata">codersdk.WorkspaceResourceMetadata</h2>
1060-
<!-- backwards compatibility -->
1059+
10611060
<a id="schemacodersdk.workspaceresourcemetadata"></a>
10621061
<a id="schema_codersdk.WorkspaceResourceMetadata"></a>
10631062
<a id="tocScodersdk.workspaceresourcemetadata"></a>
@@ -1081,7 +1080,7 @@ CoderSessionToken
10811080
|value|string|false|none|none|
10821081

10831082
<h2 id="tocS_codersdk.WorkspacesResponse">codersdk.WorkspacesResponse</h2>
1084-
<!-- backwards compatibility -->
1083+
10851084
<a id="schemacodersdk.workspacesresponse"></a>
10861085
<a id="schema_codersdk.WorkspacesResponse"></a>
10871086
<a id="tocScodersdk.workspacesresponse"></a>

‎scripts/apidocgen/generate.sh

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,9 @@ SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}")
2525
# Make sure that widdershins is installed correctly.
2626
node ./node_modules/widdershins/widdershins.js --version
2727

28-
#
28+
# Render the Markdown file.
2929
node ./node_modules/widdershins/widdershins.js \
30+
--user_templates "./markdown-template" \
3031
--search false \
3132
--omitHeader true \
3233
--language_tabs "shell:curl" \

‎scripts/apidocgen/markdown-template/README.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
## Swagger / OpenAPI 2 and OpenAPI 3 template parameters
2+
3+
Note that properties of OpenAPI objects will be in OpenAPI 3.0 form, as
4+
Swagger / OpenAPI 2.0 definitions are converted automatically.
5+
6+
### Code templates
7+
8+
* `method` - the HTTP method of the operation (in lower-case)
9+
* `methodUpper` - the HTTP method of the operation (in upper-case)
10+
* `url` - the full URL of the operation (including protocol and host)
11+
* `consumes[]` - an array of MIME-types the operation consumes
12+
* `produces[]` - an array of MIME-types the operation produces
13+
* `operation` - the current operation object
14+
* `operationId` - the current operation id
15+
* `opName` - the operationId if set, otherwise the method + path
16+
* `tags[]` - the full list of tags applying to the operation
17+
* `security` - the security definitions applying to the operation
18+
* `resource` - the current tag/path object
19+
* `parameters[]` - an array of parameters for the operation (see below)
20+
* `queryString` - an example queryString, urlEncoded
21+
* `requiredQueryString` - an example queryString for `required:true` parameters
22+
* `queryParameters[]` - a subset of `parameters` that are `in:query`
23+
* `requiredParameters[]` - a subset of `queryParameters` that are `required:true`
24+
* `headerParameters[]` - a subset of `parameters` that are `in:header`
25+
* `allHeaders[]` - a concatenation of `headerParameters` and pseudo-parameters `Accept` and `Content-Type`, and optionally `Authorization` (the latter has an `isAuth` boolean property set true so it can be omitted in templates if desired
26+
27+
### Parameter template
28+
29+
* `parameters[]` - an array of [parameters](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject), including the following pseudo-properties
30+
* `shortDesc` - a truncated version of the parameter description
31+
* `safeType` - a computed version of the parameter type, including Body and schema names
32+
* `originalType` - the original type of the parameter
33+
* `exampleValues` - an object containing examples for use in code-templates
34+
* `json` - example values in JSON compatible syntax
35+
* `object` - example values in raw object form (unquoted strings etc)
36+
* `depth` - a zero-based indicator of the depth of expanded request body parameters
37+
* `enums[]` - an array of (parameter)name/value pairs
38+
39+
### Responses template
40+
41+
* `responses[]` - an array of [responses](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject), including `status` and `meaning` properties
42+
43+
### Authentication template
44+
45+
* `authenticationStr` - a simple string of methods (and scopes where appropriate)
46+
* `securityDefinitions[]` - an array of applicable [securityDefinitions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securityRequirementObject)
47+
48+
### Schema Property template
49+
50+
* `schemaProperties[]` - an array of
51+
* `name`
52+
* `type`
53+
* `required`
54+
* `description`
55+
* `enums[]` - an array of (schema property)name/value pairs
56+
57+
### Common to all templates
58+
59+
* `openapi` - the top-level OpenAPI / Swagger document
60+
* `header` - the front-matter of the Slate/Shins markdown document
61+
* `host` - the (computed) host of the API
62+
* `protocol` - the default/first protocol of the API
63+
* `baseUrl` - the (computed) baseUrl of the API (including protocol and host)
64+
* `widdershins` - the contents of widdershins `package.json`

‎scripts/apidocgen/markdown-template/authentication.def

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<aside class="warning">
2+
To perform this operation, you must be authenticated by means of one of the following methods:
3+
{{= data.utils.getAuthenticationStr(data) }}
4+
</aside>
5+

‎scripts/apidocgen/markdown-template/authentication_none.def

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
<aside class="success">
2+
This operation does not require authentication
3+
</aside>

‎scripts/apidocgen/markdown-template/callbacks.def

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{{? typeof data.operation.callbacks === 'object'}}
2+
3+
### Callbacks
4+
5+
{{ data.operationStack.push(data.operation); }}
6+
7+
{{ for (var c of Object.keys(data.operation.callbacks)) { }}
8+
9+
#### {{=c}}
10+
11+
{{ var callback = data.operation.callbacks && data.operation.callbacks[c]; }}
12+
13+
{{ for (var e in callback) { }}
14+
{{ if (!e.startsWith('x-widdershins-')) { }}
15+
16+
**{{=e}}**
17+
18+
{{ var exp = callback[e]; }}
19+
20+
{{ for (var m in exp) { }}
21+
22+
{{ data.operation = exp[m]; }}
23+
{{ data.method.operation = data.operation; }}
24+
25+
{{= data.templates.operation(data) }}
26+
27+
{{ } /* of methods */ }}
28+
29+
{{ } /* of expressions */ }}
30+
31+
{{ } /* of if */ }}
32+
33+
{{ } /* of callbacks */ }}
34+
35+
{{ data.operation = data.operationStack.pop(); }}
36+
{{ data.method.operation = data.operation; }}
37+
38+
{{?}}

‎scripts/apidocgen/markdown-template/code_csharp.dot

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
using System;
2+
using System.Collections.Generic;
3+
using System.Net.Http;
4+
using System.Net.Http.Headers;
5+
using System.Text;
6+
using System.Threading.Tasks;
7+
using Newtonsoft.Json;
8+
9+
/// <<summary>>
10+
/// Example of Http Client
11+
/// <</summary>>
12+
public class HttpExample
13+
{
14+
private HttpClient Client { get; set; }
15+
16+
/// <<summary>>
17+
/// Setup http client
18+
/// <</summary>>
19+
public HttpExample()
20+
{
21+
Client = new HttpClient();
22+
}
23+
{{? data.methodUpper == "GET"}}
24+
/// Make a dummy request
25+
public async Task MakeGetRequest()
26+
{
27+
string url = "{{=data.url}}";
28+
var result = await GetAsync(url);
29+
}
30+
31+
/// Performs a GET Request
32+
public async Task GetAsync(string url)
33+
{
34+
//Start the request
35+
HttpResponseMessage response = await Client.GetAsync(url);
36+
37+
//Validate result
38+
response.EnsureSuccessStatusCode();
39+
40+
}{{? }}
41+
{{? data.methodUpper == "POST"}}
42+
/// Make a dummy request
43+
public async Task MakePostRequest()
44+
{
45+
string url = "{{=data.url}}";
46+
{{? data.bodyParameter.refName !== undefined }}
47+
string json = @"{{=data.bodyParameter.exampleValues.json.replace(new RegExp('"', "g"), '""')}}";
48+
{{=data.bodyParameter.refName}} content = JsonConvert.DeserializeObject(json);
49+
await PostAsync(content, url);
50+
{{? }}
51+
{{? data.bodyParameter.refName === undefined }}
52+
await PostAsync(null, url);
53+
{{? }}
54+
}
55+
56+
/// Performs a POST Request
57+
public async Task PostAsync({{=data.bodyParameter.refName}} content, string url)
58+
{
59+
//Serialize Object
60+
StringContent jsonContent = SerializeObject(content);
61+
62+
//Execute POST request
63+
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
64+
}{{? }}
65+
{{? data.methodUpper == "PUT"}}
66+
/// Make a dummy request
67+
public async Task MakePutRequest()
68+
{
69+
int id = 1;
70+
string url = "{{=data.url}}";
71+
72+
{{? data.bodyParameter.refName !== undefined }}
73+
string json = @"{{=data.bodyParameter.exampleValues.json.replace(new RegExp('"', "g"), '""')}}";
74+
{{=data.bodyParameter.refName}} content = JsonConvert.DeserializeObject(json);
75+
var result = await PutAsync(id, content, url);
76+
{{? }}
77+
{{? data.bodyParameter.refName === undefined }}
78+
var result = await PutAsync(id, null, url);
79+
{{? }}
80+
}
81+
82+
/// Performs a PUT Request
83+
public async Task PutAsync(int id, {{=data.bodyParameter.refName}} content, string url)
84+
{
85+
//Serialize Object
86+
StringContent jsonContent = SerializeObject(content);
87+
88+
//Execute PUT request
89+
HttpResponseMessage response = await Client.PutAsync(url + $"/{id}", jsonContent);
90+
91+
//Return response
92+
return await DeserializeObject(response);
93+
}{{? }}
94+
{{? data.methodUpper == "DELETE"}}
95+
/// Make a dummy request
96+
public async Task MakeDeleteRequest()
97+
{
98+
int id = 1;
99+
string url = "{{=data.url}}";
100+
101+
await DeleteAsync(id, url);
102+
}
103+
104+
/// Performs a DELETE Request
105+
public async Task DeleteAsync(int id, string url)
106+
{
107+
//Execute DELETE request
108+
HttpResponseMessage response = await Client.DeleteAsync(url + $"/{id}");
109+
110+
//Return response
111+
await DeserializeObject(response);
112+
}{{? }}
113+
{{? data.methodUpper == "POST" || data.methodUpper == "PUT"}}
114+
/// Serialize an object to Json
115+
private StringContent SerializeObject({{=data.bodyParameter.refName}} content)
116+
{
117+
//Serialize Object
118+
string jsonObject = JsonConvert.SerializeObject(content);
119+
120+
//Create Json UTF8 String Content
121+
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
122+
}
123+
{{? }}
124+
/// Deserialize object from request response
125+
private async Task DeserializeObject(HttpResponseMessage response)
126+
{
127+
//Read body
128+
string responseBody = await response.Content.ReadAsStringAsync();
129+
130+
//Deserialize Body to object
131+
var result = JsonConvert.DeserializeObject(responseBody);
132+
}
133+
}

0 commit comments

Comments
 (0)