Resultado de búsqueda
Version 2.0 specification defines a set of files required to describe an API. These files can then be used by the Swagger-UI project and Swagger-Codegen. Learn more.
- Basic Structure
Every Swagger specification starts with the Swagger version,...
- What is Swagger
Use Swagger UI to generate interactive API documentation...
- Basic Structure
Swagger Codegen. Generate server stubs and client SDKs from OpenAPI Specification definitions . Swagger Editor. API editor for designing APIs with the OpenAPI and AsyncAPI specifications. Swagger UI
Swagger UI. Visualize and interact with the API's resources without having any of the implementation logic in place. Swagger Codegen. Generate client libraries, server stubs, and API documentation from an OpenAPI Specification. Explore Open Source Tools.
- Overview
- Target Project
- Adding The Maven Dependency
- Integrating Swagger 2 Into The Project
- Swagger UI
- Spring Data Rest
- Bean Validations
- Plugin
- Advanced Configuration
- Swagger UI with An Oauth-Secured API
Nowadays, front-end and back-end components often separate a web application. Usually, we expose APIs as a back-end component for the front-end component or third-party app integrations. In such a scenario, it is essential to have proper specifications for the back-end APIs. At the same time, the API documentation should be informative, readable, a...
The creation of the REST service we will use is not within the scope of this article. If you already have a suitable project, use it. If not, these links are a good place to start: 1. Build a REST API with Spring and Java Config article 2. Building a RESTful Web Service
As mentioned above, we will use the Springfox implementation of the Swagger specification. The latest version can be found on Maven Central. To add it to our Maven project, we need a dependency in the pom.xmlfile:
4.1. Java Configuration
The configuration of Swagger mainly centers around the Docketbean: After defining the Docket bean, its select() method returns an instance of ApiSelectorBuilder, which provides a way to control the endpoints exposed by Swagger. We can configure predicates for selecting RequestHandlers with the help of RequestHandlerSelectors and PathSelectors. Using any()for both will make documentation for our entire API available through Swagger.
4.2. Configuration Without Spring Boot
In plain Spring projects, we need to enable Swagger 2 explicitly. To do so, we have to use the @EnableSwagger2 on our configuration class: Additionally, without Spring Boot, we don’t have the luxury of auto-configuration of our resource handlers. Swagger UI adds a set of resources that we must configure as part of a class that extends WebMvcConfigurerAdapter and is annotated with @EnableWebMvc:
4.3. Verification
To verify that Springfox is working, we can visit this URL in our browser: http://localhost:8080/v2/api-docs The result is a JSON response with a large number of key-value pairs, which is not very human readable. Fortunately, Swagger provides Swagger UIfor this purpose.
Swagger UI is a built-in solution that makes user interaction with the Swagger-generated API documentation much easier.
Springfox provides support for Spring Data REST through its springfox-data-restlibrary. Spring Boot will take care of the auto-configuration if it discovers the spring-boot-starter-data-rest on the classpath. Now let’s create an entity named User: Then we’ll create the UserRepository to add CRUD operations on the Userentity: Last, we’ll import the ...
Springfox also supports the bean validation annotations through its springfox-bean-validatorslibrary. First, we’ll add the Maven dependency to our pom.xml: Again, if we use Spring Boot, we don’t have to provide the above dependency explicitly. Next, let’s add a few validation annotations like @NotNull and @Min to the Userentity: Finally, we’ll impo...
In order to add specific features to the API specifications, we can create a Springfox plugin. A plugin can offer various features, from enriching the models and properties to the custom API listings and defaults. Springfox supports the plugin creation through its spi module. The spi module provides a few interfaces like the ModelBuilderPlugin, Mod...
The Docketbean of our application can be configured to give us more control over the API documentation generation process.
The Swagger UI provides a number of very useful features that we’ve covered well so far here. But we can’t really use most of these if our API is secured and not accessible. Let’s see how we can allow Swagger to access an OAuth-secured API using the Authorization Code grant type in this example. We’ll configure Swagger to access our secured API usi...
Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end ...
