Swagger Proxy Tutorial - Create a Proxy for Swagger

Synopsis

Learn how to create a service proxy for an API from a swagger description. For demonstration purposes we will use the petstore example provided on the official Swagger homepage.

1. Get Started

Download Membrane Service Proxy version 4.1.0 or higher, unzip it and navigate to the examples/swagger-proxy folder.
Linux: Execute service-proxy.sh from a command line to start Membrane Service Proxy.
Windows: Double click service-proxy.bat to start Membrane Service Proxy.

Have a look at the proxies.xml in the examples/swagger folder:

				<spring:beans xmlns="http://membrane-soa.org/proxies/1/"
				              xmlns:spring="http://www.springframework.org/schema/beans"
				              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				              xsi:schemaLocation="http://www.springframework.org/schema/beans
				              http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
				              http://membrane-soa.org/proxies/1/
				              http://membrane-soa.org/schemas/proxies-1.xsd">

					<router>

						<swaggerProxy port="7000" url="http://petstore.swagger.io/v2/swagger.json" />

						<serviceProxy port="8000">
							<swaggerRewriter />
							<target host="petstore.swagger.io" port="80" />
						</serviceProxy>

						<serviceProxy name="Console" port="9000">
							<adminConsole />
						</serviceProxy>

					</router>

				</spring:beans>
			

2. Opening the Website

Open https://localhost:7000/ in a browser. You should see a Swagger UI, explaining the petstore Swagger API.

Open another tab in your browser with the URL http://petstore.swagger.io/

The websites on localhost:7000 and petstore.swagger.io should look the same, except that all URLs on the former are rewritten to localhost:7000. You can also navigate on both sites: click on pet and explore the REST API.

3. Execute a Swagger call

Run the following calls in the command line, they should yield the same result:

curl -X GET --header "Accept: application/json" "http://localhost:7000/v2/pet/8"

curl -X GET --header "Accept: application/json" "http://petstore.swagger.io/v2/pet/8"

You just executed a Swagger call both directly to the petstore and over a Membrane Swagger Proxy.

Note: You can also conveniently run Swagger REST calls directly from the Swagger UI in your browser.

4. Explanation of the proxies.xml

There are three Service Proxies defined in the proxies.xml:

The first and the second are both Service Proxies which function as a Swagger Proxy.

The first one, the swaggerProxy

				<swaggerProxy port="7000" url="http://petstore.swagger.io/v2/swagger.json" />
			

offers a shorter and more concise way to define a Swagger Proxy, whereas the second method

				<serviceProxy port="8000">
					<swaggerRewriter />
					<target host="petstore.swagger.io" port="80" />
				</serviceProxy>
			

is more explicit and has more potential for more advanced setups.

However, even though these two methods both provide a Swagger Rewriting Proxy, they are not identical. The swaggerProxy only lets through

1. the swagger.json
2. Swagger calls which are part of the Swagger specification (swagger.json)
3. and calls to the Swagger UI. (if swaggerProxy's 'allowUI' attribute is true (default=true))

The second method - with a swaggerRewriter inside a serviceProxy - let's through all calls and redirects them to petstore.swagger.io on port 80. The swaggerRewriter takes care of rewriting the swagger.json specification and the Swagger UI (if swaggerRewriter's attribute rewriteUI is set (default=true)). When this option is set, it also rewrites the URL of html and javascript files that are transferred. Lastly, the target specifies the site which the swaggerRewriter should actually rewrite.

The third Service Proxy is just an Admin Console which you can use to watch active Service Proxies and current calls and connections.

5. Final comments

You have successfully used Membrane Service Proxy as a Swagger Proxy. This can help you with REST Web Service Integration, Service Virtualization and realization of an API Gateway.