JetBrains Rider
 
2021.3
Shortcuts: Visual Studio
Get JetBrains Rider
You are viewing the documentation for an earlier version of JetBrains Rider.
  1. Languages and frameworks
  2. OpenAPI

OpenAPI

Last modified: 07 April 2022

Required plugin: OpenAPI Specifications (bundled)

An OpenAPI Specification (OAS) is a description format for REST APIs. Swagger is a set of tools based on this specification for writing, documenting, and consuming REST APIs. For more information, see Swagger documentation.

JetBrains Rider provides coding assistance for OpenAPI definitions in YAML and JSON files, and integration with Swagger Codegen for generating server stubs, client libraries (SDKs), and documentation based on your OpenAPI specification. In addition, you can create HTTP requests for the defined endpoints and execute them via the built-in HTTP Client.

Create an OpenAPI specification

JetBrains Rider recognizes a dedicated OpenAPI Specification file type with relevant coding assistance. These are regular YAML or JSON files with the definition of the OpenAPI specification version.

Depending on the format and version, the new OpenAPI specification file contains the following template:

openapi: 3.0.0
info:
    title: Title
    description: Title
    version: 1.0.0
servers:
    - url: 'https'
paths:

If you start with an empty YAML or JSON file, you can type opnp or swag and press Tab to insert the corresponding live template.

You can use the Endpoints tool window to see all endpoints defined in your OpenAPI specifications.

Endpoints from an OpenAPI specification

Add a remote OpenAPI specification

Endpoint URLs that you define in OpenAPI specifications in your project are available for code completion. If you are writing client code for an external specification, there is no need to add it as a file to your project for auto-completing endpoint URLs. You can add a link to the relevant remote specification.

To add private OpenAPI specifications, provide your API key.

To add OpenAPI specifications from a self-hosted SwaggerHub On-Premise instance, specify the URL of your instance.

Compare OpenAPI specifications

When there is a newer specification version, you probably want to compare it against the older version to make sure that they are compatible. One way is to look at the diff Ctrl+D and compare lines that changed. However, not all changes are critical for compatibility. JetBrains Rider can compare the structure of OpenAPI specifications and create a summary of changed paths, parameters, responses, and any other elements that may break the compatibility.

Generate code from an OpenAPI specification

When you have a valid OpenAPI specification open, JetBrains Rider suggests generating code from it:

Suggestion to generate code based on the OpenAPI specification

Click Run Codegen, configure the necessary settings, then apply the changes and run the configuration. JetBrains Rider generates source code files in the specified location and shows a notification with options to open the files or import them into your project as a separate module.

Swagger Codegen run configuration

JetBrains Rider creates a Swagger Codegen run configuration, which you can configure when you run code generation for the first time for a particular file. To modify the run configuration, open Run | Edit Configurations and select the necessary configuration, or click Edit Generation Settingsthe Edit Generation Settings button at the top of the editor when the corresponding OpenAPI specification file is open.

You can configure the following common options at the top of the Swagger Codegen run configuration:

Name

Specify a name for the run/debug configuration to quickly identify it when editing or running the configuration, for example, from the Run popup Ctrl+Alt+Shift+R.

Allow parallel run

Select to allow running multiple instances of this run configuration in parallel.

By default, it is disabled, and when you start this configuration while another instance is still running, JetBrains Rider suggests to stop the running instance and start another one. This is helpful when a run/debug configuration consumes a lot of resources and there is no good reason to run multiple instances.

Store as project file

Save the file with the run configuration settings to share it with other team members. The default location is .idea/runConfigurations. However, if you do not want to share the .idea directory, you can save the configuration to any other directory within the project.

By default, it is disabled, and JetBrains Rider stores run configuration settings in .idea/workspace.xml.

General Settings

Specification path

Path to the OpenAPI specification.

Generate files to

Path to the directory for the generated files.

Generator path

Path to the generator (the executable JAR file). You can either manually specify the path to a local generator or select to use the latest available version from Maven Central.

Language

The target language of the generated code.

Configure generator

Provide configuration parameters that depend on the target language.

  • With .json file: Specify the path to config.json with configuration parameters.

    For example, your config.json file for Java can contain the following parameters:

    {
    "groupId":"com.my.company",
    "artifactId":"MyClient",
    "artifactVersion":"1.2.0",
    "library":"feign"
}

  • With properties: Specify parameters manually.

For information about the configuration parameters, see the swagger-codegen/README.md.

Advanced Settings

Custom templates path

Path to a directory with your Mustache templates.

JRE

Java runtime to use for running Swagger Codegen.

Show debug logs

Write debug messages to the log.

Before launch

Add tasks to perform before starting the run configuration in the specified order. For example, you can run another configuration or an external tool first.

Show this page

Show this run configuration settings dialog before starting it.

Activate tool window

Open the Run window when this configuration starts. If this is disabled, to open the tool window, select View | Tool Windows | Run Alt+4.

Test your OpenAPI specification in the HTTP client

When working with OpenAPI Specification files, you can create HTTP requests to the specified endpoints and execute them via the built-in HTTP client.

Create an HTTP request to an endpoint

  • In an OpenAPI specification file, click the Open in HTTP Client button in the editor gutter next to the endpoint definition.

JetBrains Rider will create a new HTTP request and save it in the generated-requests.http scratch file.

Rename an endpoint and its usages

Use the Rename refactoring to rename the defined endpoint and its usages in HTTP requests simultaneously.

  1. Do any of the following:

    • In an OpenAPI specification file, position the caret at the endpoint's definition you want to rename.

    • In an HTTP request file, position the caret at the URL path segment you want to rename.

  2. Select Refactor | Rename from the main menu or the context menu, or press Ctrl+R, R.

  3. In the Rename dialog that opens, specify the new endpoint's name.

  4. Preview and apply changes.

JetBrains Rider will rename the endpoint and its usages.