OpenAPI

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.

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

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.

1. In the Preferences dialog (⌃ ⌥ S), select Languages & Frameworks | OpenAPI Specifications.

2. 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 ⌃ 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.

Generate code from an OpenAPI specification

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

Click , configure the necessary settings, then apply the changes and run the configuration. 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.