OpenAPI

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.

AppCode 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.

Create an OpenAPI specification

AppCode 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.

Create an OpenAPI Specification manually

From the main menu, select File | New | OpenAPI Specification, or press Alt+Insert and select OpenAPI Specification.
Specify a name for the file and select the specification version and file format.

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:

                

                    {
                        "openapi": "3.0.0",
                        "info": {
                            "title": "Title",
                            "description": "Title",
                            "version": "1.0.0"
                        },
                        "servers": [
                            {
                                "url": "https"
                            }
                        ],
                        "paths": {

                        }
                    }

                

                    swagger: "2.0"
                    info:
                        title: Title
                        description: Title
                        version: 1.0.0
                    host: www
                    schemes:
                        - https
                    paths:

                

                    {
                        "swagger": "2.0",
                        "info": {
                            "title": "Title",
                            "description": "Title",
                            "version": "1.0.0"
                        },
                        "host": "www",
                        "schemes": [
                            "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.

Preview an OpenAPI specification

You can preview an OpenAPI specification using the integrated Swagger UI. When an OpenAPI specification file is opened in the editor, use and in the top-right corner to show or hide the preview.

Split editor and preview horizontally

By default, the editor and preview are split vertically (side by side), which is convenient for wide monitors. You can also split it horizontally, so that the preview is displyed in the lower part of the editor, which is more convenient for portrait displays.

In the top-right corner of the editor, click to open the Editor Preview pane.
Click again to split the editor and preview horizontally.

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.

In the Preferences dialog (Ctrl+Alt+S), select Languages & Frameworks | OpenAPI Specifications.
Click in the Remote Specifications list and specify the URL of an OpenAPI specification file or find an OpenAPI specification on SwaggerHub.

Use to reload specifications that were modified.

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. AppCode 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.

In the Project tool window, select two OpenAPI specification files, right-click them and select Compare OpenAPI Specifications.

This generates a Markdown file with a summary of modified specification elements. The file opens in the editor with a preview panel that makes it easy to navigate the changes. It shows the changes in the file that you selected second compared to the first one.

Generate code from an OpenAPI specification

When you have a valid OpenAPI specification open, you can generate code from it by clicking :

Generate code based on the OpenAPI specification

Click in the gutter and select Run 'openapi file'. AppCode 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

AppCode creates a Swagger Codegen run configuration 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 in the gutter and select Modify Run Configuration.

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

Name

Specify a name for the run configuration to quickly identify it among others when editing or running.

Allow multiple instances

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, AppCode suggests stopping the running instance and starting another one. This is helpful when a run 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 AppCode 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. 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 path	Java runtime to use for running Swagger Codegen.
Show debug logs	Write debug messages to the log.

Last modified: 28 March 2023