Appia OpenAPI Language Server

Language Server that interacts with the Appia Marketplace and provides OpenAPI auto-completion and validation.

Configuration

Configure the VSCode extension by clicking the ⚙ icon.

• Set the value of the Appia Marketplace URL to the full URL of the Appia Marketplace.

  In the example below, the value https://appia-marketplace.example.com is used.

• Make sure your file has an extension, e.g. json or yaml

Additional Information

• Disable GitHub copilot (for that specific file).
• File should be saved to enable to the extension.
• Indentation is important! Main entries should not be indented.

Autocomplete

The x-appia-consume-from property can be auto completed and can do a lot of necessary scaffolding for you. However, there are some quirks to be aware of:

• The first time can take > 18 seconds to load the list of URLs to consume from (after that it will faster).
• Be conscious about the letters you type as it will directly try to filter the results (best to first start with one letter).
  • either scroll through the whole list.
  • make the x-appia-consume-from value more specific to make the list smaller.
  • fill the entries, e.g. url found from swagger, completely, then enter the semicolon and trigger the autocomplete.

Usage

When creating a consumer API specification you can create a new file that starts with openapi: 3.0.0. You should have a document like

openapi: 3.0.0

First, select the source that you want to use for auto-completing your consuming OpenAPI specification. Auto-complete the property x-appia-consume-from.

openapi: 3.0.0
x- # <-- autocomplete here

You should see auto-completions for the property x-appia-consume-from.

Then, auto-complete one of the API specification sources. The document at that URL will be used as the source of your consuming OpenAPI specification. For example, to use the specification of the Web Gateway, select the URL https://appia-marketplace.example.com/gateway/web.json.

You should now have the document that contains servers, an information block, tags and security.

Add some APIs and components by auto-completing the paths block.

openapi: 3.0.0
x-appia-consume-from: https://appia-marketplace.example.com/gateway/web.json

p # <-- autocomplete here

# other things

The paths property should be auto-completed.

Now, select one of the available APIs:

openapi: 3.0.0
x-appia-consume-from: https://appia-marketplace.example.com/gateway/web.json

paths:
  / # <-- autocomplete here

# other things

Then select one of the APIs. For the example, we will use /demo-service/information.

Next, auto-complete the available HTTP methods, for example GET:

openapi: 3.0.0
x-appia-consume-from: https://appia-marketplace.example.com/gateway/web.json

paths:
  /demo-service/information:
    g # <-- autocomplete here

# other things

The entire contents of the API will be auto-completed, including the operation (API specification), the request and response specification and the corresponding models.

Ordering of the entries in the file doesn't matter, but it should include:

• openapi: (manual entry)
• x-appia-consume-from: (semi-automatic entry)
• servers: (autogenerated via url behind x-appia-consume-from)
• info: (autogenerated via url behind x-appia-consume-from)
• tags: (autogenerated via url behind x-appia-consume-from)
• paths: (semi-automatic entry)
• components: (autogenerated via entry behind paths)