Swagger Search is an application that aggregates the Swagger/OpenAPI documentation of your microservice architecture in one place, where your can browse it or search endpoints based on their url, documentation, the parameters it accepts or their types.
Swagger Search also provides a Swagger UI for those microservices that haven't their own Swagger UI embedded.
The available fields are:
- service-name: the name specified on the info->title of the swagger doc or the basePath
- path: of the endpoint
- method: GET/POST/...
- parameters: name of the query/form/path/header parameter, or in the case of a body param, the name of any of the properties of the object or nested objects.
- responses: the name of any of the properties of the object or nested objects of any of the responses
- types: name of any $ref in parameters or responses
If no field is specified, all of them will be used.
Swagger UI and proxy
For each service, Swagger Search will try to find if that service comes with its own Swagger UI.
If it does, Swagger Search will use that UI when you click on a search result for that particular service.
If it does not, Swagger Search will use its own Swagger UI and a proxy to forward the requests.
Note that this proxy is very naive, so do not expose it outside your trusted network as it does not do any validations.
First you need to create a configuration file. Look at the example, which contains all the configuration options.
Copy or make the swagger.config.edn avaible in /config inside the container, something like:
docker run -p 7878:3000 -v `pwd`/examples:/config danlebrero/swagger-search
Open a browser at http://localhost:7878/
See DockerHub for the latest version.
Instead of Docker, you can just run the application manually as a JVM application:
- Install Java 8
- Download the latest release jar
- Specify the SWAGGER_HOME directory as a environment variable
- Place the configuration file in the SWAGGER_HOME directory. It must be called swagger.config.edn
java -jar swaggersearch-vXXXX.jar
Open a browser at http://localhost:$whatever-port-you-specified-in-the-config-file/
Custom service discovery
Swagger Search needs to find out what services you are running. The built-in options are:
- Hardcoded list
- Read a local file
- Read a url
The configuration example file has more details about each of them.
It is quite possible that none of these suits you, in which case next are the possible options to user your own service discovery
I dont know Clojure!
Your best option is to learn Clojure. It will do you a lot of good
Failing that, use the :uri-or-file provider and have a process that updates the file or write some HTTP server that is able to return the list of services.
Plugin a new provider
To create your own service discovery mechanism:
- Create a function like the Etcd one
- Package it
- Either add the package to the classpath or copy it to $SWAGGER_HOME/libs
- Add any additional jar dependencies to the classpath or to $SWAGGER_HOME/libs
Swagger Search as a library
If you don't want to run Docker or Uberjar, Swagger Search is also available as a library in Clojars.
See the uberjar code as guide about how you can use it as a library.
- No support for OpenAPI 3.0.
- Swagger 1.2 and below just indexes the url.
- Index is stored in memory.
Go to examples/etcd and run:
This should start a whole developer environment, including an application with a sample Swagger API.
Swagger Search will be available at http://localhost:8504/ and a Clojure REPL at localhost:8503
Copyright © 2017 IG Group
Distributed under Apache Licence 2.0.