Skip to content

Commit a8e9c9a

Browse files
grantgrant
authored
docs: add API extractor (#354)
* docs: add API extractor Signed-off-by: Grant Timmerman <[email protected]> * ci: fix lint Signed-off-by: Grant Timmerman <[email protected]> * feat: update api extractor setup Signed-off-by: Grant Timmerman <[email protected]> * fix: remove temp files Signed-off-by: Grant Timmerman <[email protected]> * refactor: move generated docs to generated section Signed-off-by: Grant Timmerman <[email protected]> * docs: update contributing doc path Signed-off-by: Grant Timmerman <[email protected]> * fix: export Data as well Signed-off-by: Grant Timmerman <[email protected]>
1 parent aba9cb4 commit a8e9c9a

15 files changed

+2156
-15
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ yarn-error.log
1313
function_output.json
1414
serverlog_stderr.txt
1515
serverlog_stdout.txt
16+
temp

‎CONTRIBUTING.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,16 @@ npm unpublish @google-cloud/[email protected]
7171
npm dist-tag add @google-cloud/[email protected] latest --registry=https://wombat-dressing-room.appspot.com
7272
```
7373

74+
### API Extractor
75+
76+
To generate the API Extractor documentation, run the API extractor with the following command:
77+
78+
```sh
79+
npm run docs
80+
```
81+
82+
The docs will be generated in [`docs/generated/`](docs/generated/).
83+
7484
## Community Guidelines
7585

7686
This project follows [Google's Open Source Community

‎api-extractor.json

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
{
2+
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
3+
4+
"mainEntryPointFilePath": "build/src/index.d.ts",
5+
"bundledPackages": [],
6+
"compiler": {
7+
"tsconfigFilePath": "tsconfig.json"
8+
},
9+
"apiReport": {
10+
"enabled": true,
11+
"reportFolder": "docs/generated/",
12+
"reportFileName": "api.md"
13+
},
14+
15+
"docModel": {
16+
"enabled": true,
17+
"apiJsonFilePath": "docs/generated/api.json"
18+
},
19+
20+
"dtsRollup": {
21+
"enabled": true,
22+
"untrimmedFilePath": "docs/generated/api.d.ts",
23+
"omitTrimmingComments": true
24+
},
25+
26+
"tsdocMetadata": {
27+
},
28+
29+
"messages": {
30+
"compilerMessageReporting": {
31+
"default": {
32+
"logLevel": "warning"
33+
}
34+
},
35+
36+
"extractorMessageReporting": {
37+
"default": {
38+
"logLevel": "warning"
39+
}
40+
},
41+
42+
"tsdocMessageReporting": {
43+
"default": {
44+
"logLevel": "warning"
45+
}
46+
}
47+
}
48+
}

‎docs/README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,14 @@ This directory contains advanced docs around the Functions Framework.
88
- [Writing a Function in Typescript](typescript.md)
99
- [ES Modules](esm/README.md)
1010

11+
## Generated Docs
12+
13+
The `generated/` directory contains generated API references.
14+
15+
- [api.md](generated/api.md)
16+
- [api.d.ts](generated/api.d.ts)
17+
- [api.json](generated/api.json)
18+
1119
## TODO Docs
1220

1321
- Run Multiple Cloud Functions [#23](https://github.com/GoogleCloudPlatform/functions-framework-nodejs/issues/23)

‎docs/generated/api.d.ts

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
import * as express from 'express';
2+
3+
/**
4+
* Register a function that handles CloudEvents.
5+
* @param functionName - the name of the function
6+
* @param handler - the function to trigger when handling cloudevents
7+
* @public
8+
*/
9+
export declare const cloudevent: (functionName: string, handler: CloudEventFunction) => void;
10+
11+
/**
12+
* A cloudevent function handler.
13+
* @public
14+
*/
15+
export declare interface CloudEventFunction {
16+
(cloudevent: CloudEventsContext): any;
17+
}
18+
19+
/**
20+
* A cloudevent function handler with callback.
21+
* @public
22+
*/
23+
export declare interface CloudEventFunctionWithCallback {
24+
(cloudevent: CloudEventsContext, callback: Function): any;
25+
}
26+
27+
/**
28+
* The CloudEvents v1.0 context object for the event.
29+
* {@link https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes}
30+
* @public
31+
*/
32+
export declare interface CloudEventsContext {
33+
/**
34+
* Type of occurrence which has happened.
35+
*/
36+
type?: string;
37+
/**
38+
* The version of the CloudEvents specification which the event uses.
39+
*/
40+
specversion?: string;
41+
/**
42+
* The event producer.
43+
*/
44+
source?: string;
45+
/**
46+
* ID of the event.
47+
*/
48+
id?: string;
49+
/**
50+
* Timestamp of when the event happened.
51+
*/
52+
time?: string;
53+
/**
54+
* Describes the subject of the event in the context of the event producer.
55+
*/
56+
subject?: string;
57+
/**
58+
* A link to the schema that the event data adheres to.
59+
*/
60+
dataschema?: string;
61+
/**
62+
* Content type of the event data.
63+
*/
64+
datacontenttype?: string;
65+
/**
66+
* The event data.
67+
*/
68+
data?: Record<string, unknown | string | number | boolean> | string | number | boolean | null | unknown;
69+
/**
70+
* The traceparent string, containing a trace version, trace ID, span ID, and trace options.
71+
* @see https://github.com/cloudevents/spec/blob/master/extensions/distributed-tracing.md
72+
*/
73+
traceparent?: string;
74+
}
75+
76+
/**
77+
* The Cloud Functions context object for the event.
78+
* {@link https://cloud.google.com/functions/docs/writing/background#function_parameters}
79+
* @public
80+
*/
81+
export declare interface CloudFunctionsContext {
82+
/**
83+
* A unique ID for the event. For example: "70172329041928".
84+
*/
85+
eventId?: string;
86+
/**
87+
* The date/time this event was created. For example: "2018-04-09T07:56:12.975Z"
88+
* This will be formatted as ISO 8601.
89+
*/
90+
timestamp?: string;
91+
/**
92+
* The type of the event. For example: "google.pubsub.topic.publish".
93+
*/
94+
eventType?: string;
95+
/**
96+
* The resource that emitted the event.
97+
*/
98+
resource?: string | {
99+
[key: string]: string;
100+
};
101+
}
102+
103+
/**
104+
* The function's context.
105+
* @public
106+
*/
107+
export declare type Context = CloudFunctionsContext | CloudEventsContext;
108+
109+
/**
110+
* A data object used for legacy event functions.
111+
* @public
112+
*/
113+
export declare interface Data {
114+
data: object;
115+
}
116+
117+
/**
118+
* A legacy event function handler.
119+
* @public
120+
*/
121+
export declare interface EventFunction {
122+
(data: {}, context: Context): any;
123+
}
124+
125+
/**
126+
* A legacy event function handler with callback.
127+
* @public
128+
*/
129+
export declare interface EventFunctionWithCallback {
130+
(data: {}, context: Context, callback: Function): any;
131+
}
132+
133+
/**
134+
* A function handler.
135+
* @public
136+
*/
137+
export declare type HandlerFunction = HttpFunction | EventFunction | EventFunctionWithCallback | CloudEventFunction | CloudEventFunctionWithCallback;
138+
139+
/**
140+
* Register a function that responds to HTTP requests.
141+
* @param functionName - the name of the function
142+
* @param handler - the function to invoke when handling HTTP requests
143+
* @public
144+
*/
145+
export declare const http: (functionName: string, handler: HttpFunction) => void;
146+
147+
/**
148+
* A HTTP function handler.
149+
* @public
150+
*/
151+
export declare interface HttpFunction {
152+
(req: express.Request, res: express.Response): any;
153+
}
154+
155+
/**
156+
* A legacy event function context.
157+
* @public
158+
*/
159+
export declare type LegacyCloudFunctionsContext = CloudFunctionsContext | Data;
160+
161+
/**
162+
* A legacy event.
163+
* @public
164+
*/
165+
export declare interface LegacyEvent {
166+
data: {
167+
[key: string]: any;
168+
};
169+
context: CloudFunctionsContext;
170+
}
171+
172+
export { }

0 commit comments

Comments
 (0)