Skip to content

Commit 577fc01

Browse files
beezythebotbeezythebot
committed
Sync open source content 🐝 (from 4121dd40b9ed8a9195586d11fa3c854e54e7520a)
1 parent e7215fd commit 577fc01

34 files changed

+3480
-113
lines changed

‎_meta.global.tsx‎

Lines changed: 30 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ const meta = {
245245
},
246246
"using-environments-with-vercel-ai-sdk": {
247247
title: "Using environments with the Vercel AI SDK",
248-
}
248+
},
249249
},
250250
},
251251
},
@@ -691,6 +691,17 @@ const meta = {
691691
},
692692
},
693693
},
694+
guides: {
695+
title: "Guides",
696+
items: {
697+
overlays: {
698+
title: "Overlays",
699+
},
700+
hooks: {
701+
title: "Hooks",
702+
},
703+
},
704+
},
694705
},
695706
},
696707
"docs-md": {
@@ -754,6 +765,9 @@ const meta = {
754765
},
755766
},
756767
},
768+
guides: {
769+
title: "Guides",
770+
},
757771
},
758772
},
759773
/*
@@ -815,6 +829,15 @@ const meta = {
815829
supported: {
816830
title: "Supported",
817831
},
832+
extensions: {
833+
title: "Extensions",
834+
},
835+
"workflow-file": {
836+
title: "Workflow File",
837+
},
838+
guides: {
839+
title: "Guides",
840+
},
818841
},
819842
},
820843

@@ -1042,6 +1065,12 @@ const meta = {
10421065
},
10431066
},
10441067
},
1068+
pagination: {
1069+
title: "Pagination",
1070+
},
1071+
guides: {
1072+
title: "Guides",
1073+
},
10451074
"release-notes-section": {
10461075
type: "separator",
10471076
title: <SidebarSeparator>{"Release Notes"}</SidebarSeparator>,
@@ -1153,116 +1182,6 @@ const meta = {
11531182
},
11541183
},
11551184
},
1156-
guides: {
1157-
title: "Guides",
1158-
type: "page",
1159-
display: "children",
1160-
items: {
1161-
"search-bar-guides": {
1162-
type: "separator",
1163-
title: "__INKEEP_SEARCH__",
1164-
},
1165-
index: {
1166-
title: "Overview",
1167-
},
1168-
openapi: {
1169-
title: "OpenAPI Guides",
1170-
items: {
1171-
"x-codesamples": {
1172-
title: "Code Samples Extension",
1173-
},
1174-
"path-fragments": {
1175-
title: "Path Fragments",
1176-
},
1177-
"publish-specs-to-api-registry": {
1178-
title: "Publish Specs to API Registry",
1179-
},
1180-
},
1181-
},
1182-
1183-
sdks: {
1184-
title: "SDK Guides",
1185-
items: {
1186-
"creating-a-monorepo": {
1187-
title: "Create a Monorepo",
1188-
},
1189-
"utilizing-user-agent-strings": {
1190-
title: "User Agent Strings",
1191-
},
1192-
"generate-in-a-subdirectory": {
1193-
title: "Generate in a Subdirectory",
1194-
},
1195-
"typescript-monorepo-tips": {
1196-
title: "TypeScript Monorepo Tips",
1197-
},
1198-
"pnpm-default": {
1199-
title: "Using PNPM",
1200-
},
1201-
"override-compile": {
1202-
title: "Override Compile Commands",
1203-
},
1204-
overlays: {
1205-
title: "SDK Overlays",
1206-
items: {
1207-
overlays: {
1208-
title: "Common Overlays for SDKs",
1209-
},
1210-
"internal-external-versions": {
1211-
title: "Internal and External SDKs",
1212-
},
1213-
"json-path-expressions": {
1214-
title: "JSON Path Expressions",
1215-
},
1216-
},
1217-
},
1218-
},
1219-
},
1220-
hooks: {
1221-
title: "Hook Guides",
1222-
items: {
1223-
"env-auth-hook": {
1224-
title: "Environment Auth Hook",
1225-
},
1226-
"posthog-telemetry-hook": {
1227-
title: "PostHog Telemetry Hook",
1228-
},
1229-
"sentry-error-hook": {
1230-
title: "Sentry Error Hook",
1231-
},
1232-
"user-agent-hook": {
1233-
title: "User Agent Hook",
1234-
},
1235-
},
1236-
},
1237-
1238-
terraform: {
1239-
title: "Terraform Guides",
1240-
items: {
1241-
crud: {
1242-
title: "CRUD Example",
1243-
},
1244-
hoisting: {
1245-
title: "Hoisting",
1246-
},
1247-
"merged-entity": {
1248-
title: "Merged Entity",
1249-
},
1250-
"remove-nontf-endpoints": {
1251-
title: "Remove Non-TF Endpoints",
1252-
},
1253-
},
1254-
},
1255-
1256-
cli: {
1257-
title: "CLI Guides",
1258-
items: {
1259-
"code-samples-without-github-actions": {
1260-
title: "Populate Code Samples Without GitHub Actions",
1261-
},
1262-
},
1263-
},
1264-
},
1265-
},
12661185
mcp: {
12671186
title: "MCP Hub",
12681187
type: "page",

‎docs/sdks/guides/creating-a-monorepo.mdx‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: "Create a monorepo"
3+
description: "Create a monorepo with Speakeasy and Github."
4+
---
5+
6+
import { Callout } from "@/mdx/components";
7+
8+
9+
<Callout title="Warning" type="warning">
10+
This section outlines an advanced setup process that may not be suitable for all users. For most use cases, we recommend adopting the simpler approach of a single SDK per GitHub repository. To setup a single SDK per Github see our [SDK quickstart](/docs/sdks/create-client-sdks).
11+
</Callout>
12+
13+
# What is a Monorepo?
14+
15+
A monorepo is a unified repository containing multiple SDKs, each corresponding to a unique OpenAPI specification. This approach offers a centralized location for discovering available SDKs while allowing for the independent download and management of each SDK as needed. Each SDK resides in its own subfolder, and can be made complete with individual GitHub workflows for regeneration and release processes.
16+
17+
18+
## Repository Structure
19+
20+
The monorepo's structure is designed for scalability and easy navigation. In our example, we will discuss two SDKs: ServiceA and ServiceB, each found in their respective subfolders. The typical structure of such a monorepo is as follows:
21+
22+
```yaml
23+
.github/workflows/
24+
- serviceA_generate.yaml # Github Workflow for generating the ServiceA SDK, generated by speakeasy cli
25+
- serviceA_release.yaml # Github Workflow for releasing and publishing the ServiceA SDK, generated by speakeasy cli
26+
- serviceB_generate.yaml # Github Workflow for generating the ServiceB SDK, generated by speakeasy cli
27+
- serviceB_release.yaml # Github Workflow for releasing and publishing the ServiceB SDK, generated by speakeasy cli
28+
.speakeasy/workflow.yaml # Speakeasy workflow file that dictates mapping of sources (eg: openapi docs) and targets (eg: language sdks) to generate
29+
serviceA/
30+
- gen.yaml # Generation config for the ServiceA SDK
31+
serviceB/
32+
- gen.yaml # Generation config for the ServiceB SDK
33+
```
34+
This structure can be expanded to accommodate any number of SDKs.
35+
36+
## Creating Your SDK Monorepo
37+
38+
You have two options for creating your SDK monorepo with Speakeasy and GitHub: starting from a template or building from scratch. For the purpose of this guide, we will use an example with two APIs, one for `lending` and one for `accounting`.
39+
40+
### Option 1: Use a Template
41+
Start by cloning the [`template-sdk-monorepo` repository](https://github.com/speakeasy-sdks/template-sdk-monorepo?tab=readme-ov-file) using the "Use template" button on GitHub, and name it as you see fit.
42+
43+
### Option 2: Build from Scratch
44+
1. Create a new repository on GitHub and clone it down locally with `git clone <repo-url>`.
45+
2. Mimic the directory structure shown above. This can be achieved easily by following the interactive CLI commands below
46+
47+
a. Install Speakeasy CLI
48+
49+
b. Use quickstart to boostrap the repository.
50+
51+
This will create the necessary directories and files for you to start generating SDKs.
52+
53+
```bash
54+
speakeasy quickstart
55+
```
56+
57+
When prompted make sure to choose a sub directory rather than the root of your directory for generating the first target. We will add more targets in the following steps.
58+
59+
c. Configure your sources
60+
61+
```bash
62+
speakeasy configure sources
63+
```
64+
For each source reference a local or remote OpenAPI document. Optionally add in an overlay if needed. Each source you configure here will be used
65+
to point towards a generation target in the following step.
66+
67+
![Screenshot of configuring sources for monorepo.](/assets/guides/monorepo-step-2c.png)
68+
69+
d. Configure your targets
70+
71+
For each target referenced a local or remote OpenAPI document. Optionally add in an overlay if needed. For ever target make sure to choose a
72+
a language, a source and a subdirectory to generate the target in. In the provided example `accounting` and `lending` are two sub directories in which we'll generate two different targets for two different sources.
73+
74+
```bash
75+
speakeasy configure targets
76+
```
77+
78+
![Screenshot of configuring targets for monorepo.](/assets/guides/monorepo-step-2d.png)
79+
80+
#### Final Speakeasy Workflow
81+
82+
The final speakeasy workflow file will look like the following
83+
84+
```yaml
85+
workflowVersion: 1.0.0
86+
speakeasyVersion: latest
87+
sources:
88+
accounting:
89+
inputs:
90+
- location: /path/to/accounting/openapi.yaml
91+
lending:
92+
inputs:
93+
- location: /path/to/lending/openapi.yaml
94+
targets:
95+
accounting-ts:
96+
target: typescript
97+
source: accounting
98+
output: ./accounting
99+
lending-ts:
100+
target: typescript
101+
source: lending
102+
output: ./lending
103+
```
104+
105+
106+
#### Setup Github Release and Publishing Workflows
107+
108+
Finally if you want your SDKs to be regenerated and published in their Github repos setup the workflow files needed for remote generation and publishing. The CLI can help you set up these files with:
109+
110+
```bash
111+
speakesy configure publishing
112+
```
113+
114+
Follow the prompts to setup your secrets in Github Action Secrets. Push up the repo to your remote location and watch everything spin!
115+
116+
### Configure Generation
117+
118+
Edit the `gen.yaml` file in the root of each SDK's subfolder. This file dictates the generator settings, including package name, class names, parameter inlining, and other preferences. For complete documentation on all the available publishing configurations, see [here](/docs/speakeasy-reference/generation/gen-yaml).
119+
120+
## Generate SDKs
121+
122+
### Locally
123+
124+
Simply run `speakeasy run` and select the SDKs you wish to regenerate. Use `speakaesy run --force` if there are no OpenAPI document changes.
125+
126+
![Screenshot of running all targets for monorepo.](/assets/guides/monorepo-step-run.png)
127+
128+
### Github
129+
130+
To manually trigger SDK generation:
131+
1. Navigate to the Actions tab in your GitHub repository.
132+
2. Select the generation workflow for the SDK you wish to generate.
133+
3. Click "Run workflow" to start the generation process. Check mark the "Force" input option if there are no OpenAPI document changes.
134+
135+
## Verify your SDK
136+
137+
After generation, review the SDK to ensure it aligns with your requirements.

‎docs/sdks/guides/generate-in-a-subdirectory.mdx‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: "Generate SDK in a subdirectory"
3+
description: "Setup your SDK in a subdirectory."
4+
---
5+
6+
import { Screenshot } from "@/mdx/components";
7+
8+
# Generate SDK in a Subdirectory
9+
10+
Similar to setting up a monorepo, you can also configure Speakeasy to generate your SDK into a subdirectory. This setup maybe useful in maintaining seperation between handwritten and generated code or for consuming the SDK in a monolithic codebase.
11+
12+
## Step 1:
13+
14+
In the root of your existing directory run `speakeasy quickstart`:
15+
16+
<Screenshot
17+
variant="cli"
18+
image={{
19+
src: "/assets/docs/create-sdks/guides/generate-in-a-subdirectory/1.png",
20+
alt: "A screenshot of the speakeasy quickstart command in the CLI."
21+
}}
22+
/>
23+
24+
## Step 2:
25+
26+
Select your generation language.
27+
28+
<Screenshot
29+
variant="cli"
30+
image={{
31+
src: "/assets/docs/create-sdks/guides/generate-in-a-subdirectory/2.png",
32+
alt: "A screenshot of the CLI prompting the user to select their generation language."
33+
}}
34+
/>
35+
36+
## Step 3:
37+
38+
Name your package.
39+
40+
<Screenshot
41+
variant="cli"
42+
image={{
43+
src: "/assets/docs/create-sdks/guides/generate-in-a-subdirectory/3.png",
44+
alt: "A screenshot of the package name in the Speakeasy CLI."
45+
}}
46+
/>
47+
48+
## Step 4:
49+
50+
If you're setting your SDK up in a folder with existing subfolders, you will be prompted to select an output directory.
51+
52+
<Screenshot
53+
variant="cli"
54+
image={{
55+
src: "/assets/docs/create-sdks/guides/generate-in-a-subdirectory/4.png",
56+
alt: "A screenshot of the user being prompted to provide an output directory in the CLI."
57+
}}
58+
/>
59+
60+
## Step 5:
61+
62+
Complete generating your SDK.
63+
64+
<Screenshot
65+
variant="cli"
66+
image={{
67+
src: "/assets/docs/create-sdks/guides/generate-in-a-subdirectory/5.png",
68+
alt: "A screenshot of a succesful CLI generation."
69+
}}
70+
/>
71+
72+
Going forward to generate your SDK navigate to your SDK folder and run `speakeasy run`.

0 commit comments

Comments
 (0)