diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index c6bc370ab..1afc859f5 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -389,7 +389,7 @@ whitelabel: username: "company-github-username" email: "my-email@example.com" token: "ghp_xxxxxxxxxxxx" - +``` The GitHub username that will be used for committing and publishing the whitelabeled SDK code to GitHub repositories. This should be the username of the account that has write access to your target repositories. @@ -499,11 +499,12 @@ default-group: "production" ## groups -Organizes different sets of generators (like "production" vs "staging" vs "internal") + +Organizes user-defined sets of generators, typically grouped by environment (like "production", "staging") or language (like "typescript", "python"). ```yaml groups: - production: + company-typescript: # User-defined name audiences: ["external"] generators: - name: fernapi/fern-typescript-node-sdk @@ -513,226 +514,308 @@ groups: package-name: "@myorg/api-sdk" token: "${NPM_TOKEN}" github: - repository: "myorg/typescript-sdk" - mode: "release" - config: - clientName: "MyApiClient" - packageName: "@myorg/api-sdk" - metadata: - package-description: "Official TypeScript SDK" - author: "MyOrg SDK Team" - keywords: ["CustomKeyword"] - snippets: - path: "./snippets" - smart-casing: true - api: - settings: - inline-path-parameters: true - - name: fernapi/fern-python-sdk - version: 2.0.0 - output: - location: pypi - package-name: "myorg-api-sdk" - token: "${PYPI_TOKEN}" - metadata: - keywords: ["api", "sdk"] - documentation-link: "https://docs.myorg.com" + repository: your-organization/company-typescript + mode: "pull-request" metadata: - description: "Production SDKs for MyAPI" + description: "TypeScript SDK for MyAPI" authors: - name: "SDK Team" email: "sdk@myorg.com" reviewers: teams: - name: "sdk-team" - users: - - name: "john-doe" ``` - + +Target audiences for this generator group (e.g., "external", "internal") - - - - +### reviewers - - +Who should review generated code for a specific group. - - + - - +### generators -### Generator Configuration +```yaml +groups: + company-typescript: # User-defined name + audiences: ["external"] + generators: + - name: fernapi/fern-typescript-node-sdk + version: 0.9.0 +``` - - +Individual generator settings within a group. - + +The Fern generator package name (e.g., fernapi/fern-typescript-node-sdk) - + +Specific version of the generator to use - - +#### output - - +Configuration for where and how to publish the generated SDK - - +```yaml +groups: + company-typescript: # User-defined name + audiences: ["external"] + generators: + - name: fernapi/fern-typescript-node-sdk + version: 0.9.0 + output: + location: npm + package-name: "@myorg/api-sdk" + token: "${NPM_TOKEN}" +``` - - + + - - +Publish TypeScript/JavaScript SDKs to NPM registry. + +```yaml +output: + location: npm + package-name: "@myorg/api-sdk" + token: "${NPM_TOKEN}" +``` - + +Set to "npm" for NPM publishing - + +Custom NPM registry URL - + +NPM package name (e.g., "@myorg/api-sdk") - + +NPM authentication token for publishing + + -### Output Locations +Publish Java SDKs to Maven repository. -#### NPM Output +```yaml +output: + location: maven + coordinate: "com.myorg:api-sdk" + username: "${MAVEN_USERNAME}" + password: "${MAVEN_PASSWORD}" + signature: + keyId: "ABC123" + password: "${GPG_PASSWORD}" + secretKey: "${GPG_SECRET_KEY}" +``` - + +Set to "maven" for Maven publishing - + +Maven repository URL (optional, defaults to Maven Central) - + +Maven artifact coordinate in "groupId:artifactId" format - + +Repository authentication username -#### Maven Output - - + +Repository authentication password - + +GPG signature configuration for package signing - + +GPG key ID for package signing - + +GPG key password - + +GPG secret key content + + - - +Publish Python SDKs to Python Package Index. - - +```yaml +output: + location: pypi + package-name: "myorg-api-sdk" + token: "${PYPI_TOKEN}" + metadata: + keywords: ["api", "sdk", "client"] + documentation-link: "https://docs.myorg.com" + homepage-link: "https://myorg.com" +``` - + +Set to "pypi" for PyPI publishing - + +Custom PyPI registry URL (optional, defaults to PyPI) -#### PyPI Output - - + +Python package name (e.g., "myorg-api-sdk") - + +PyPI authentication token for publishing - + +PyPI username (alternative to token authentication) - + +PyPI password (alternative to token authentication) - + +Additional PyPI-specific metadata for the package - + +Package keywords for PyPI search and discovery - + +Link to package documentation - + +Link to project homepage + - - + - - +Publish .NET SDKs to NuGet repository. -#### NuGet Output +```yaml +output: + location: nuget + package-name: "MyOrg.ApiSdk" + api-key: "${NUGET_API_KEY}" +``` - + +Set to "nuget" for NuGet publishing - + +Custom NuGet feed URL (optional, defaults to nuget.org) - + +NuGet package name (e.g., "MyOrg.ApiSdk") - + +NuGet API key for publishing to the feed + + -#### RubyGems Output +Publish Ruby SDKs to RubyGems registry. - +```yaml +output: + location: rubygems + package-name: "myorg_api_sdk" + api-key: "${RUBYGEMS_API_KEY}" +``` + + +Set to "rubygems" for RubyGems publishing - + +Custom RubyGems registry URL (optional, defaults to rubygems.org) - + +Ruby gem package name (e.g., "myorg_api_sdk") - + +RubyGems API key for publishing (requires "Push rubygem" permission) -#### Postman Output +> **Note**: RubyGems API keys need "Push rubygem" permission and ideally "index" and "yank rubygem" permissions. If MFA is enabled, ensure MFA settings don't require MFA for API key usage. + + + +Publish API collections to Postman workspace. + +```yaml +output: + location: postman + api-key: "${POSTMAN_API_KEY}" + workspace-id: "12345678-1234-1234-1234-123456789abc" + collection-id: "87654321-4321-4321-4321-cba987654321" +``` - + +Set to "postman" for Postman publishing - + +Postman API key for workspace access - + +Target Postman workspace ID where collection will be published - + +Existing collection ID to update (creates new collection if not specified) + + -#### Local File System Output +Save generated SDKs to local file system instead of publishing. + +```yaml +output: + location: local-file-system + path: "./generated-sdks/typescript" +``` - + +Set to "local-file-system" for local output - + +Local directory path where generated files will be saved + + -### GitHub Configuration +#### github Specify how your SDKs are generated in GitHub using the `github` configuration. Designate the `mode` to specifiy how Fern handles your code changes. For all of the @@ -741,8 +824,8 @@ SDK code. You can also configure a branch name, license, and reviewers. Make sure the [Fern GitHub app](https://github.com/apps/fern-api) is installed on your destination repository - -#### Release (recommended) + + Fern generates your code, commits it to main, and tags a new release. @@ -772,8 +855,8 @@ groups: Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1). - -#### Pull request + + Fern generates your code, commits to a new branch, and opens a PR for review. To publish, you must merge the PR and tag a GitHub release. @@ -803,8 +886,8 @@ groups: Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1). - -#### Push + + Fern generates your code and pushes it to the branch you specify. @@ -834,8 +917,10 @@ groups: Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1). + + -### Generator Metadata +#### metadata Specify metadata for your SDK generator. @@ -872,7 +957,7 @@ Name of the individual developer, team, or organization that created and maintai Software license for the generated SDK. -### Snippets Configuration +#### snippets Configures snippets for a particular generator. @@ -890,13 +975,14 @@ groups: The path to the generated snippets file. -### Override API Authentication Settings +#### Override API Authentication Settings Override authentication settings in your API spec using the `api` configuration. You can specify authentication schemes, reference existing auth configurations, and set additional API-specific settings. -#### Single Authentication Scheme + + Reference a pre-defined authentication scheme by name. @@ -913,8 +999,8 @@ groups: The authentication scheme to use. Can be either a string reference (`"bearer-token"`) or scheme object (`scheme: "bearer-token"`). - -#### Multiple Authentication Options + + Allow users to authenticate with any of several methods: @@ -935,9 +1021,9 @@ groups: A list of authentication schemes where users can choose any one method. Each item can be either a string reference (`"api-key"`) or scheme object (`scheme: "api-key"`). + - -#### Custom Authentication Schemes + Define a custom authentication schemes using `auth-schemes`. You define a name for your custom scheme, and then specify the authentication method (`header`, `basic`, `bearer`, or `oauth`). @@ -988,27 +1074,11 @@ groups: -## reviewers -Who should review generated code. - -```yaml -reviewers: - teams: - - name: "sdk-team" - - name: "api-team" - users: - - name: "john-doe" - - name: "jane-smith" -``` + + - - GitHub team names that should review generated code. - +### reviewers - - GitHub users that should review generated code. - +Who should review generated code for all groups. - -Name of a GitHub team or a user. - \ No newline at end of file + diff --git a/fern/products/sdks/snippets/reviewers-params.mdx b/fern/products/sdks/snippets/reviewers-params.mdx new file mode 100644 index 000000000..ee7a4e817 --- /dev/null +++ b/fern/products/sdks/snippets/reviewers-params.mdx @@ -0,0 +1,22 @@ + +```yaml +reviewers: + teams: + - name: "sdk-team" + - name: "api-team" + users: + - name: "john-doe" + - name: "jane-smith" +``` + + + GitHub team names that should review generated code. + + + + GitHub users that should review generated code. + + + +Name of a GitHub team or a user. + \ No newline at end of file