Hello World Sample

Please note that this example is using Swagger version 1.2 while the latest version is 2.0

---

In this example we'll show you how to create your first Swagger Specification based files to describe a simple Hello World application. We'll then show you how to view those files using Swagger-UI.

Note that in this sample application, we are not conforming to a good API design but rather we present a very simple use case.

Since this is a sample application intended to be ran locally, we'll assume the host to be localhost and the port to be 8000.

Application Structure

For the purpose of this example, let's assume we have a greetings resource, with a hello operation that has a {subject} path parameter. As such, our operation URL would be:

http://localhost:8000/greetings/hello/{subject}

Calling such a URL with a GET operation will give us back a 200 (OK) HTTP response with a simple text reply saying 'Hello {subject}' where {subject} is the path parameter we used. As such, calling http://host/greetings/hello/world will give us back 'Hello world'.

Swagger Endpoint Structure

Normally, the entry point to Swagger would be the api-docs resource, located at the context root. Since this is a simple application, the context root here is just the host.

This means that in order to see the Swagger documentation, you should open:

http://localhost:8000/api-docs

The document you'll see here is what we refer to as the Resource Listing as it gives you a list of resources that your application exposes.

We have one resource in this application - greetings. While not mandatory, the most common usage is to use the resource name under the Swagger root to give out information about that resource. So in this case, the URL would be:

http://localhost:8000/api-docs/greetings

This document is the known as the API Declaration as it provides information about the operation exposed on this specific resource.

Since we're going to use static hosting in this sample, and we want to keep things simple, we're going to have to change the default way of service the API Declaration. We're going to serve static files, and it's just impossible to have the following file structure:

/
|- api-docs
|- api-docs/
           |-greetings

Granted, you can configure different URL mappings in your web server, but in order to keep it simple, we'll host the greetings API Declaration using this URL:

http://localhost:8000/listings/greetings

The Resource Listing

Our first step is to generate the resource listing file (normally served as api-docs). For more an extended explanation of the resource listing, check out the relevant section in the Swagger Specification.

Our most basic resource listing would look as such:

{
  "swaggerVersion": "1.2",
  "apis": [
    {
      "path": "http://localhost:8000/listings/greetings",
      "description": "Generating greetings in our application."
    }
  ]
}

In the simplest form, there are two fields that are required:

1. swaggerVersion - This indicates the version of the Swagger Specification being used. This field is mandatory to allow various automated processing know how to read the generated spec files (by Swagger-UI for example, or the code generator).
2. apis - This lists the resources we expose in our application. In this case, there's one resource under "http://localhost:8000/listings/greetings" and we give it a simple description as to its responsibility. After all, Swagger is about describing your API. As mentioned before, normally, the value of path here would simply be "/greetings" which is the relative URL from api-docs.

The API Declaration

The next step is to describe the API from the Resource Listing. For more an extended explanation of the API declaration, check out the relevant section in the Swagger Specification.

Our API declaration would look as such:

{
  "swaggerVersion": "1.2",
  "basePath": "http://localhost:8000/greetings",
  "apis": [
    {
      "path": "/hello/{subject}",
      "operations": [
        {
          "method": "GET",
          "summary": "Greet our subject with hello!",
          "type": "string",
          "nickname": "helloSubject",
          "parameters": [
            {
              "name": "subject",
              "description": "The subject to be greeted.",
              "required": true,
              "type": "string",
              "paramType": "path"
            }
          ]
        }
      ]
    }
  ],
  "models": {}
}

Let's take a look at this json file.

Again, we have a swaggerVersion field, for the same reason we had it in the resource listing. It is being repeated as each of the files can be accessed independently and this information is required for proper processing.

The basePath is the root for this resource, which in this case is greetings. Swagger uses the basePath to build and execute API calls if needed. It assumes that all the APIs and operations in this given file are relative to the basePath. Do not confuse the basePath with the path in the Resource Listing. The basePath points to the actual resource whereas the path in the Resource Listing points to the location where that resource is documented by Swagger.

Here too we have an apis field. This time it is used to list all the API calls available on this resource. We have one path here - "/hello/{subject}". Here we can see the declaration of {subject} which is known as a path parameter. This means it can be substituted with any string value and the application will treat it as an input parameter. For this reason, we can see in the parameters array that we have one parameter of type "path". Since it's part of the path, it is also mandatory, hence required is true. The name of the parameter is also "subject" as it is in the path. The description field will be used by Swagger UI to give a brief explanation of the parameter, however, it may also be useful for anyone reading the JSON files directly.

Going back to the operation declaration, we can see a few other fields. The summary is a brief explanation of what this operation does.

We decided that we want this call to use the HTTP GET method, so we indicate that using the method field. We also noted that we want to return a string, and so the type is string.

The nickname field is a unique name for the operation that must not include white spaces. This name is used by other tools (such as Swagger UI or the code generator) to perform their tasks. For example, the code generator will use this name as the method name it generates for the client.

Running it with Swagger UI

To run this static sample, we'll provide you with two options.

Serve the files on your server

Fire up whichever web server you favor, and serve the two static files. For ease of use, we've provided you with the sample files here.

Once you have your web server up and running, go ahead and clone Swagger-UI. Follow the directions there on how to run it, and direct it at your api-docs file.

Use the all-in-one package

If you're familiar with maven, we've provided you with an all-in-one package. This includes the static files, the Swagger-UI application and an instance of jetty to run it all together. Take a look here and follow the instructions in the README.md.

What next?

So you've finished this brief tutorial and hopefully have a better understanding of what Swagger is about. You can either go over the full specification or go through any of the Swagger-related project listed here.