Spring Boot 简明教程

Spring Boot - Enabling Swagger2

Swagger2 是一个用于为 RESTful Web 服务生成 REST API 文档的开源项目。它提供了一个用户界面,能够通过网络浏览器访问我们的 RESTful Web 服务。

Swagger2 is an open source project used to generate the REST API documents for RESTful web services. It provides a user interface to access our RESTful web services via the web browser.

要启用 Spring Boot 应用程序中的 Swagger2,您需要在我们的构建配置中添加以下依赖项。

To enable the Swagger2 in Spring Boot application, you need to add the following dependencies in our build configurations file.

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.7.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.7.0</version>
</dependency>

对于 Gradle 用户,请在 build.gradle 文件中添加以下依赖项。

For Gradle users, add the following dependencies in your build.gradle file.

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0'

接下来,在您的主要 Spring Boot 应用程序中添加 @EnableSwagger2 注解。@EnableSwagger2 注解用于为您的 Spring Boot 应用程序启用 Swagger2。

Now, add the @EnableSwagger2 annotation in your main Spring Boot application. The @EnableSwagger2 annotation is used to enable the Swagger2 for your Spring Boot application.

主要 Spring Boot 应用程序的代码如下所示:

The code for main Spring Boot application is shown below −

package com.tutorialspoint.swaggerdemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication {
   public static void main(String[] args) {
      SpringApplication.run(SwaggerDemoApplication.class, args);
   }
}

接下来,创建一个 Docket Bean 以配置您的 Spring Boot 应用程序的 Swagger2。我们需要定义基本包以配置 REST API 以供 Swagger2 使用。

Next, create Docket Bean to configure Swagger2 for your Spring Boot application. We need to define the base package to configure REST API(s) for Swagger2.

@Bean
   public Docket productApi() {
      return new Docket(DocumentationType.SWAGGER_2).select()
         .apis(RequestHandlerSelectors.basePackage("com.tutorialspoint.swaggerdemo")).build();
   }

现在,将此 Bean 添加到 Spring Boot 主应用程序类文件中,您的 Spring Boot 主应用程序类将如下所示:

Now, add this bean in main Spring Boot application class file itself and your main Spring Boot application class will look as shown below −

package com.tutorialspoint.swaggerdemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication {
   public static void main(String[] args) {
      SpringApplication.run(SwaggerDemoApplication.class, args);
   }
   @Bean
   public Docket productApi() {
      return new Docket(DocumentationType.SWAGGER_2).select()
         .apis(RequestHandlerSelectors.basePackage("com.tutorialspoint.swaggerdemo")).build();
   }
}

现在,在您的构建配置文件中添加以下 Spring Boot Starter Web 依赖项以编写 REST 端点,具体如下所示:

Now, add the below Spring Boot Starter Web dependency in your build configuration file to write a REST Endpoints as shown below −

Maven 用户可以在他们的 pom.xml 文件中添加以下依赖 −

Maven users can add the following dependency in your pom.xml file −

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Gradle 用户可以在 build.gradle 文件中添加以下依赖项:

Gradle users can add the following dependency in build.gradle file −

compile('org.springframework.boot:spring-boot-starter-web')

现在,通过如下所示,此处展示了在 Rest Controller 文件中构建两个简单的 RESTful Web 服务 GET 和 POST 的代码:

Now, the code to build two simple RESTful web services GET and POST in Rest Controller file is shown here −

package com.tutorialspoint.swaggerdemo;

import java.util.ArrayList;
import java.util.List;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SwaggerAPIController {
   @RequestMapping(value = "/products", method = RequestMethod.GET)
   public List<String> getProducts() {
      List<String> productsList = new ArrayList<>();
      productsList.add("Honey");
      productsList.add("Almond");
      return productsList;
   }
   @RequestMapping(value = "/products", method = RequestMethod.POST)
   public String createProduct() {
      return "Product is saved successfully";
   }
}

完整的构建配置文件如下所示 −

The complete build configuration file is given below −

Maven – pom.xml

Maven – pom.xml

<?xml version = "1.0" encoding = "UTF-8"?>
<project xmlns = "http://maven.apache.org/POM/4.0.0"
   xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation = "http://maven.apache.org/POM/4.0.0
   http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>

   <groupId>com.tutorialspoint</groupId>
   <artifactId>swagger-demo</artifactId>
   <version>0.0.1-SNAPSHOT</version>
   <packaging>jar</packaging>
   <name>swagger-demo</name>
   <description>Demo project for Spring Boot</description>

   <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>1.5.9.RELEASE</version>
      <relativePath /> <!-- lookup parent from repository -->
   </parent>

   <properties>
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
      <java.version>1.8</java.version>
   </properties>

   <dependencies>
      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-web</artifactId>
      </dependency>

      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-test</artifactId>
         <scope>test</scope>
      </dependency>

      <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger2</artifactId>
         <version>2.7.0</version>
      </dependency>

      <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger-ui</artifactId>
         <version>2.7.0</version>
      </dependency>
   </dependencies>

   <build>
      <plugins>
         <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
         </plugin>
      </plugins>
   </build>

</project>

Gradle – build.gradle

Gradle – build.gradle

buildscript {
   ext {
      springBootVersion = '1.5.9.RELEASE'
   }
   repositories {
      mavenCentral()
   }
   dependencies {
      classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
   }
}
apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'org.springframework.boot'

group = 'com.tutorialspoint'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = 1.8

repositories {
   mavenCentral()
} dependencies {
   compile('org.springframework.boot:spring-boot-starter-web')
   testCompile('org.springframework.boot:spring-boot-starter-test')
   compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0'
   compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0'
}

您可以创建一个可执行 JAR 文件,并通过使用以下 Maven 或 Gradle 命令来运行 Spring Boot 应用程序。

You can create an executable JAR file, and run the Spring Boot application by using the following Maven or Gradle commands.

对于 Maven,您可以使用此处所示的命令:

For Maven, you can use the command shown here −

mvn clean install

“BUILD SUCCESS”之后,您可以在目标目录中找到 JAR 文件。

After “BUILD SUCCESS”, you can find the JAR file under the target directory.

对于 Gradle,您可以使用此处所示的命令:

For Gradle, you can use the command as shown here −

gradle clean build

“BUILD SUCCESSFUL”之后,您可以在 build/libs 目录中找到 JAR 文件。

After “BUILD SUCCESSFUL”, you can find the JAR file under the build/libs directory.

现在,通过使用此处所示命令运行 JAR 文件:

Now, run the JAR file by using the command shown here −

java –jar <JARFILE>

现在,应用程序将启动在 Tomcat 端口 8080 中,具体如下所示:

Now, the application will start on the Tomcat port 8080 as shown −

started application on tomcat port 8080

现在,在您的网络浏览器中访问该 URL,然后查看 Swagger API 功能。

Now, hit the URL in your web browser and see the Swagger API functionalities.

swagger api functionalities