- Welcome to the Swagger sample project!
- Exploring the REST API with a built in Swagger UI client
- Exploring the REST API with stand alone Swagger UI
- Generate static HTML documentation
- Automation
- The Big Picture
- Feedback
This sample application focuses on swagger and its possible usage scenarios in Spring Boot porjects. CI is taken into account. Several scenarios are discussed here.
- generating the Swagger API specification with springfox in a running server
- using the Swagger UI which is built in the application
- using the stand alone Swagger UI
- generating static REST API documentation
- generating swagger spec as build artifact
- using the swagger spec in project automation
To start the application clone the project. It comes with gradlew wrapper so the only thing that should be executed from within the project directory is:
gradlew bootRun
This will start a server locally at port 8080.
The application may be imported in Eclipse as an existing project. To do so from the project directory execute:
gradlew eclipse
Open eclipse and import the project as existing java project.
The REST API is currently secured with Basic Authentication. The application has one built in user with name lucho and password test.
Start the application. This application comes with a built in Swagger UI client. It is exposed at the following endpoint http://localhost:8080/swagger-ui.html.
This endpoint is normally not available in production system thus the application is configured to expose it only when the current active profile is dev. The application is by default started with this profile. The UI should look similar to the one below (at the time of writing).
Start the application. It is neither required nor even recommended to bundle Swagger UI with the application the standalone client might be used. Clone the Sagger UI. This may take some time. Change to swagger-ui\dist and open index.html within your browser. In the URL input at the top of the page enter the URL of the Swagger Specification exposed by the application. This should be http://localhost:8080/v2/api-docs. Click explore.
Start the application. Download a binary distribution of swagger codegen CLI, for example from Maven. Note: check if newer version is available. Place the jar file in a directory of your choice and navigate to this directory. If the java environment is step correctly the following could be executed:
java -jar swagger-codegen-cli-2.2.2.jar generate -l html2 -i http://localhost:8080/v2/api-docs -o docs
The command will generate static HTML documentation and store it in the docs folder. All this is not as good as Swagger UI and looks like this at the time of writing:
Everything about springfox is nice but in order to generate a swagger specification the server needs to be running. This may not be perfect for CI. The swagger specification may be reqired in build time when there is no running server.
At the time of writing there is no very good support for gradle. Maven is the favoured build system. There is a nice maven plugin. This project uses a gradle port of the plugin. To generate swagger specification execute:
gradlew build
gradlew swagger
The swagger spec is available under the project root in \generated\swagger-json. The swagger spec may be used in various ways, e.g. it may be even tried out in the online swagger editor. It can be deployed as a release artifact.
The project comes with a sample gradle plugin for swagger2markup which is able to generate Ascii Doc from the swagger specification. To see it in action execute:
gradlew build
gradlew swagger
gradlew convertSwagger2markup -b swagger2makup.gradle
The output will be generated in under generated/asciidoc. Sample rendering:
A mock MVC starts a minimalistic server which is capable enough to serve the swagger spec. A test case may be used to persist this spec. To try this out run:
gradlew clean test
The output will be normally generated under generated\swagger-test.
Below is a diagram which may show "the big picture" emerging from all those usage scenarios above.
