Einrichten von Swagger 2 mit einer Spring REST-API

Sicherheit Top

Ich habe gerade den neuen Learn Spring Security-Kurs angekündigt, einschließlich des vollständigen Materials zum neuen OAuth2-Stack in Spring Security 5:

>> PRÜFEN SIE DEN KURSREST Oben

Ich habe gerade den neuen Learn Spring- Kurs angekündigt , der sich auf die Grundlagen von Spring 5 und Spring Boot 2 konzentriert:

>> Überprüfen Sie den Kurs

1. Übersicht

Heutzutage trennen Front-End- und Back-End-Komponenten häufig eine Webanwendung. Normalerweise stellen wir APIs als Back-End-Komponente für die Front-End-Komponente oder für App-Integrationen von Drittanbietern bereit.

In einem solchen Szenario ist es wichtig, über die richtigen Spezifikationen für die Back-End-APIs zu verfügen. Gleichzeitig sollte die API-Dokumentation informativ, lesbar und leicht zu befolgen sein.

Darüber hinaus sollte die Referenzdokumentation gleichzeitig jede Änderung in der API beschreiben. Dies manuell durchzuführen ist eine mühsame Übung, daher war eine Automatisierung des Prozesses unvermeidlich.

In diesem Tutorial sehen wir uns Swagger 2 für einen Spring REST-Webdienst an , der die Springfox-Implementierung der Swagger 2-Spezifikation verwendet.

Wenn Sie mit Swagger nicht vertraut sind, besuchen Sie die Webseite, um mehr zu erfahren, bevor Sie mit diesem Tutorial fortfahren.

2. Zielprojekt

Die Erstellung des von uns verwendeten REST-Service fällt nicht in den Geltungsbereich dieses Artikels. Wenn Sie bereits ein geeignetes Projekt haben, verwenden Sie es. Wenn nicht, sind diese Links ein guter Anfang:

  • Erstellen Sie eine REST-API mit Spring 4 und Java Config
  • Erstellen eines RESTful-Webdienstes

3. Hinzufügen der Maven-Abhängigkeit

Wie oben erwähnt, verwenden wir die Springfox-Implementierung der Swagger-Spezifikation. Die neueste Version finden Sie auf Maven Central.

Um es unserem Maven-Projekt hinzuzufügen, benötigen wir eine Abhängigkeit in der Datei pom.xml :

 io.springfox springfox-swagger2 2.9.2 

3.1. Spring Boot-Abhängigkeit

Für die Spring Boot-basierten Projekte reicht es aus, eine einzelne Springfox-Boot-Starter- Abhängigkeit hinzuzufügen :

 io.springfox springfox-boot-starter 3.0.0 

4. Integration von Swagger 2 in das Projekt

4.1. Java-Konfiguration

Die Konfiguration von Swagger konzentriert sich hauptsächlich auf die Docket- Bean:

@Configuration public class SpringFoxConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } }

Nach dem Definieren der Docket- Bean gibt die Methode select () eine Instanz von ApiSelectorBuilder zurück , mit der die von Swagger bereitgestellten Endpunkte gesteuert werden können.

Wir können Prädikate für die Auswahl von RequestHandler mit Hilfe von RequestHandlerSelectors und PathSelectors konfigurieren . Wenn Sie any () für beide verwenden, wird die Dokumentation für unsere gesamte API über Swagger verfügbar.

4.2. Konfiguration ohne Spring Boot

In einfachen Spring-Projekten müssen wir Swagger 2 explizit aktivieren. Dazu müssen wir @ EnableSwagger2WebMvc für unsere Konfigurationsklasse verwenden :

@Configuration @EnableSwagger2WebMvc public class SpringFoxConfig { }

Darüber hinaus haben wir ohne Spring Boot nicht den Luxus, unsere Ressourcenhandler automatisch zu konfigurieren.

Die Swagger-Benutzeroberfläche fügt eine Reihe von Ressourcen hinzu, die wir als Teil einer Klasse konfigurieren müssen, die WebMvcConfigurerAdapter erweitert und mit @EnableWebMvc versehen ist:

@Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); }

4.3. Überprüfung

Um zu überprüfen, ob Springfox funktioniert, können wir diese URL in unserem Browser besuchen:

// localhost: 8080 / spring-security-rest / api / v2 / api-docs

Das Ergebnis ist eine JSON-Antwort mit einer großen Anzahl von Schlüssel-Wert-Paaren, die nicht sehr gut lesbar ist. Glücklicherweise bietet Swagger zu diesem Zweck die Swagger-Benutzeroberfläche an.

5. Swagger-Benutzeroberfläche

Die Swagger-Benutzeroberfläche ist eine integrierte Lösung, die die Benutzerinteraktion mit der von Swagger generierten API-Dokumentation erheblich vereinfacht.

5.1. Aktivieren der Swagger-Benutzeroberfläche von Springfox

Um die Swagger-Benutzeroberfläche verwenden zu können, müssen wir eine zusätzliche Maven-Abhängigkeit hinzufügen:

 io.springfox springfox-swagger-ui 2.9.2 

Jetzt können wir es in unserem Browser testen, indem wir besuchen:

// localhost: 8080 / your-app-root / swagger-ui /

In unserem Fall lautet die genaue URL übrigens:

// localhost: 8080 / spring-security-rest / api / swagger-ui /

Das Ergebnis sollte ungefähr so ​​aussehen:

5.2. Erkundung der Swagger-Dokumentation

Within Swagger’s response is a list of all controllers defined in our application. Clicking on any of them will list the valid HTTP methods (DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT).

Expanding each method provides additional useful data, such as response status, content-type, and a list of parameters. It is also possible to try each method using the UI.

Swagger’s ability to be synchronized with our code base is crucial. To demonstrate this, we can add a new controller to our application:

@RestController public class CustomController { @RequestMapping(value = "/custom", method = RequestMethod.POST) public String custom() { return "custom"; } }

Now if we refresh the Swagger documentation, we see custom-controller in the list of controllers. As we know, there is only one method (POST) shown in Swagger’s response.

6. Spring Data REST

Springfox provides support for Spring Data REST through its springfox-data-rest library.

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:

@Entity public class User { @Id private Long id; private String firstName; private int age; private String email; // getters and setters }

Then we'll create the UserRepository to add CRUD operations on the User entity:

@Repository public interface UserRepository extends CrudRepository { }

Last, we'll import the SpringDataRestConfiguration class to the SpringFoxConfig class:

@EnableSwagger2WebMvc @Import(SpringDataRestConfiguration.class) public class SpringFoxConfig { //... }

Note: We've used the @EnableSwagger2WebMvc annotation to enable Swagger, as it has replaced the @EnableSwagger2 annotation in version 3 of the libraries.

Let's restart the application to generate the specifications for the Spring Data REST APIs:

We can see that Springfox has generated the specifications for the User entity with HTTP methods like GET, POST, PUT, PATCH, and DELETE.

7. Bean Validations

Springfox also supports the bean validation annotations through its springfox-bean-validators library.

First, we'll add the Maven dependency to our pom.xml:

 io.springfox springfox-bean-validators 2.9.2 

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 User entity:

@Entity public class User { //... @NotNull(message = "First Name cannot be null") private String firstName; @Min(value = 15, message = "Age should not be less than 15") @Max(value = 65, message = "Age should not be greater than 65") private int age; }

Finally, we'll import the BeanValidatorPluginsConfiguration class to the SpringFoxConfig class:

@EnableSwagger2 @Import(BeanValidatorPluginsConfiguration.class) public class SpringFoxConfig { //... }

Let's take a look at the changes in the API specifications:

Here, we can observe that the User model has * required on the firstName. Also, the minimum and maximum values are defined for the age.

8. Plugin

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, ModelPropertyBuilderPlugin, and ApiListingBuilderPlugin that act as an extensibility hook to implement a custom plugin.

To demonstrate the capabilities, let's create a plugin to enrich the email property of the User model. We'll use the ModelPropertyBuilderPlugin interface and set the values of the pattern and example.

First, let's create the EmailAnnotationPlugin class and override the supports method to allow any documentation type, such as Swagger 1.2 and Swagger 2:

@Component @Order(Validators.BEAN_VALIDATOR_PLUGIN_ORDER) public class EmailAnnotationPlugin implements ModelPropertyBuilderPlugin { @Override public boolean supports(DocumentationType delimiter) { return true; } }

Then we'll override the apply method of the ModelPropertyBuilderPlugin to set the values of the builder properties:

@Override public void apply(ModelPropertyContext context) { Optional email = annotationFromBean(context, Email.class); if (email.isPresent()) { context.getSpecificationBuilder().facetBuilder(StringElementFacetBuilder.class) .pattern(email.get().regexp()); context.getSpecificationBuilder().example("[email protected]"); } }

So, the API specifications will show the pattern and example values of the property annotated with the @Email annotation.

Next, we'll add the @Email annotation to the User entity:

@Entity public class User { //... @Email(regexp=".*@.*\\..*", message = "Email should be valid") private String email; }

Last, we'll enable the EmailAnnotationPlugin in the SpringFoxConfig class by registering as a bean:

@Import({BeanValidatorPluginsConfiguration.class}) public class SpringFoxConfig { //... @Bean public EmailAnnotationPlugin emailPlugin() { return new EmailAnnotationPlugin(); } }

Let's check out the EmailAnnotationPlugin in action:

We can see the value of the pattern is the same regex (.*@.*\\..*) from the email property of the User entity.

Similarly, the value of the example ([email protected]) is the same, as defined in the apply method of the EmailAnnotationPlugin.

9. Advanced Configuration

The Docket bean of our application can be configured to give us more control over the API documentation generation process.

9.1. Filtering API for Swagger’s Response

It is not always desirable to expose the documentation for the entire API. We can restrict Swagger’s response by passing parameters to the apis() and paths() methods of the Docket class.

As seen above, RequestHandlerSelectors allows using the any or none predicates but can also be used to filter the API according to the base package, class annotation, and method annotations.

PathSelectors provides additional filtering with predicates, which scan the request paths of our application. We can use any(), none(), regex(), or ant().

In the example below, we will instruct Swagger to include only controllers from a particular package, with specific paths, using the ant() predicate:

@Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.baeldung.web.controller")) .paths(PathSelectors.ant("/foos/*")) .build(); }

9.2. Custom Information

Swagger also provides some default values in its response, which we can customize, such as “Api Documentation”, “Created by Contact Email”, and “Apache 2.0”.

To change these values, we can use the apiInfo(ApiInfo apiInfo) method — the ApiInfo class that contains custom information about the API:

@Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.ant("/foos/*")) .build() .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfo( "My REST API", "Some custom description of API.", "API TOS", "Terms of service", new Contact("John Doe", "www.example.com", "[email protected]"), "License of API", "API license URL", Collections.emptyList()); }

9.3. Custom Methods Response Messages

Swagger allows globally overriding response messages of HTTP methods through Docket’s globalResponseMessage()method.

First, we need to instruct Swagger not to use default response messages. Suppose we want to override 500 and 403 response messages for all GET methods.

To achieve this, some code must be added to the Docket’s initialization block (original code is excluded for clarity):

.useDefaultResponseMessages(false) .globalResponseMessage(RequestMethod.GET, newArrayList(new ResponseMessageBuilder() .code(500) .message("500 message") .responseModel(new ModelRef("Error")) .build(), new ResponseMessageBuilder() .code(403) .message("Forbidden!") .build()));

10. Swagger UI With an OAuth-Secured API

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 using the SecurityScheme and SecurityContext support:

@Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2).select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build() .securitySchemes(Arrays.asList(securityScheme())) .securityContexts(Arrays.asList(securityContext())); }

10.1. The Security Configuration

We'll define a SecurityConfiguration bean in our Swagger configuration and set some defaults:

@Bean public SecurityConfiguration security() { return SecurityConfigurationBuilder.builder() .clientId(CLIENT_ID) .clientSecret(CLIENT_SECRET) .scopeSeparator(" ") .useBasicAuthenticationWithAccessCodeGrant(true) .build(); }

10.2. SecurityScheme

Next, we'll define our SecurityScheme; this is used to describe how our API is secured (Basic Authentication, OAuth2, …).

In our case here, we'll define an OAuth scheme used to secure our Resource Server:

private SecurityScheme securityScheme() { GrantType grantType = new AuthorizationCodeGrantBuilder() .tokenEndpoint(new TokenEndpoint(AUTH_SERVER + "/token", "oauthtoken")) .tokenRequestEndpoint( new TokenRequestEndpoint(AUTH_SERVER + "/authorize", CLIENT_ID, CLIENT_SECRET)) .build(); SecurityScheme oauth = new OAuthBuilder().name("spring_oauth") .grantTypes(Arrays.asList(grantType)) .scopes(Arrays.asList(scopes())) .build(); return oauth; }

Note that we used the Authorization Code grant type, for which we need to provide a token endpoint and the authorization URL of our OAuth2 Authorization Server.

And here are the scopes we need to have defined:

private AuthorizationScope[] scopes() { AuthorizationScope[] scopes = { new AuthorizationScope("read", "for read operations"), new AuthorizationScope("write", "for write operations"), new AuthorizationScope("foo", "Access foo API") }; return scopes; }

These sync up with the scopes we actually have defined in our application, for the /foos API.

10.3. SecurityContext

Finally, we need to define a SecurityContext for our example API:

private SecurityContext securityContext() { return SecurityContext.builder() .securityReferences( Arrays.asList(new SecurityReference("spring_oauth", scopes()))) .forPaths(PathSelectors.regex("/foos.*")) .build(); }

Note how the name we used here in the reference — spring_oauth — syncs up with the name we used previously in the SecurityScheme.

10.4. Test

Now that we have everything set up and ready to go, let's take a look at our Swagger UI and try access the Foo API.

We can access the Swagger UI locally:

//localhost:8082/spring-security-oauth-resource/swagger-ui.html

As we can see, a new Authorize button now exists due to our security configurations:

When we click the Authorize button, we can see the following pop-up to authorize our Swagger UI to access the secured API:

Note that:

  • We can already see the CLIENT_ID and CLIENT_SECRET, as we've pre-configured them earlier (but we can still change them).
  • We can now select the scopes we need.

Here's how the secured API is marked:

And now, finally, we can hit our API!

Natürlich ist es fast selbstverständlich, dass wir vorsichtig sein müssen, wie wir die Swagger-Benutzeroberfläche extern verfügbar machen, da diese Sicherheitskonfiguration jetzt aktiv ist.

11. Schlussfolgerung

In diesem Artikel haben wir Swagger 2 eingerichtet, um Dokumentation für eine Spring REST-API zu generieren. Wir haben auch Möglichkeiten untersucht, die Ausgabe von Swagger zu visualisieren und anzupassen. Und schließlich haben wir uns eine einfache OAuth-Konfiguration für Swagger angesehen.

Die vollständige Implementierung dieses Tutorials finden Sie im GitHub-Projekt. Schauen Sie sich dieses GitHub-Modul an, um das Setup in einem Boot-Projekt zu sehen.

Für den Abschnitt OAuth ist der Code in unserem Spring-Security-Oauth-Repository verfügbar.

Und wenn Sie ein Schüler von REST With Spring sind, lesen Sie in Lektion 1 von Modul 7, wie Sie Swagger mit Spring and Spring Boot einrichten.

Sicherheit unten

Ich habe gerade den neuen Learn Spring Security-Kurs angekündigt, einschließlich des vollständigen Materials zum neuen OAuth2-Stack in Spring Security 5:

>> PRÜFEN SIE DEN KURSREST unten

Ich habe gerade den neuen Learn Spring- Kurs angekündigt , der sich auf die Grundlagen von Spring 5 und Spring Boot 2 konzentriert:

>> Überprüfen Sie den Kurs