External Services: Introduction to Swagger Schema

Hi! 🙋🏻‍♂️

Following up on my recent post on introduction to External Services, in this post we’re gonna discuss what is a Swagger Schema. This is probably the trickiest part when working with External Services, so let’s see what it really is.

What is Swagger Schema?

Before knowing what a Swagger schema is, let’s understand what is OpenAPI Specification because you’re gonna hear this term a lot.

OpenAPI Specification, originally known as the Swagger Specification, is a specification(a set of standards) for describing, producing, consuming, and visualizing REST APIs.

So what is Swagger then? Well, Swagger provides us with a toolset for implementing this API specification.

So your Swagger Schema( can also be called OpenAPI schema) contains information describing your callout request endpoints, inputs and outputs w.r.t a particular REST API.

How do I get started with writing Swagger Schemas?

To understand how a schema is defined, first you MUST have a fundamental knowledge about things that fall under the umbrella term ‘Integration’ like, APIs, Authentication*, callouts/request, Request Methods, Request Parameters, Request Response etc.

I’m linking two short YouTube videos that can help you understand it better, feel free to skip though.

• What is API?(3 mins)
• REST API concepts and examples (8 mins)

*Authentication is something that you don’t have to deal with while writing Swagger schema because it’s handled automatically by Named Credentials. Topic for another post! 😉

Now that you have ‘some’ understanding, you can start to get your hands dirty. To get started with swagger schema, you should bookmark this OpenAPI 2.0 specs guide. This guide has all the specifications that you need to follow to define a schema.

NOTE: Make sure you only follow OpenAPI 2.0 specs to write your schemas because External services currently DO NOT support OpenAPI 3.0 specs.

To write your schema definition, you can use editor.swagger.io**. It’s one of the Swagger tools that helps you write, validate and test your schema very easily.

**Make sure you’re writing for schema in JSON and NOT in YAML format.

Now let’s take a quick look of how a HTTP request/callout translates into OpenAPI 2.0 spec.

Translating HTTP callout to Swagger definition

The following describes how an HTTP callout translates into a swagger definition.

Considerations

As always, this discussion is also incomplete without some considerations. I’d strongly recommend taking a look at the considerations for external services before you start implementing solutions for your customers.

NOTE: This might be a lot of info to digest at the beginning but as you start to write more and more schemas, you’ll feel more confident with time.

Feel free to drop your questions in the comments.

Hope you find this one useful! Catch you in the next one! ✌
And thank you for being an awesome reader! Subscribe to this blog for receiving all the latest updates straight to your inbox. 🙂