Swagger UI 用于生成交互式 API 文档，让您可以直接在浏览器中尝试 REST 服务调用。

在本指南中，让我们构建一个简单的 Spring Boot REST 服务并将 Swagger UI 集成到该服务中。这让我们可以使用 Spring Boot 集成的 Swagger UI 在浏览器中直接测试我们的 REST 服务。

目录

1. 创建 spring boot 应用程序（汽车库存服务）
2. 创建 REST 服务
3. 启动应用程序
4. 在浏览器中启动 Swagger UI
5. 禁用 Swagger 用户界面
6. Swagger REST API 文档

创建 spring boot 应用程序（汽车库存服务）

使用时构建裸机 Spring Boot 服务很简单Spring Initializr。Spring Initializr使用您快速启动所需的内容生成 Spring Boot 项目！让我们从一个开始。

使用 Spring Initializr 创建 Spring Boot 启动项目

让我们利用此处Spring Initializr提供的预配置来创建spring-boot-swagger-integration启动项目。

单击生成项目。这将下载一个包含spring-boot-swagger-integration项目的 zip 文件。将项目导入您的 IDE。

创建 REST 服务

添加 REST 服务方法

使用 2 种方法创建一个 Rest Service 接口 -addCar(car)和viewCars().

com.codeaches.carinventoryservice.CarInventoryControllerInterface.java

public interface CarInventoryControllerInterface {

  public String addCar(@RequestBody(required = true) String car);
  public Set<String> viewCars();
}

为其余服务接口添加和实现类。

com.codeaches.carinventoryservice.CarInventoryController.java

@RestController
public class CarInventoryController implements CarInventoryControllerInterface {

  @PostMapping("addCar")
  public String addCar(@RequestBody String car) {
    cars.add(car);
    return car;
  }

  @GetMapping("viewCars")
  public Set<String> viewCars() {
    return cars;
  }

  static Set<String> cars = new HashSet<>();
  static {
    cars.add("Toyota");
    cars.add("Benz");
  }
}

添加 Swagger 注释和 UI 依赖项

添加下面提到的依赖项，用于添加 Swagger UI 和在我们的 java 代码中使用 Swagger 注释。

pom.xml

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

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

启用 Swagger 用户界面

SwaggerDocumentationConfig.java使用 spring @Bean 注解创建一个新配置并定义一个 Docket 实例。

com.codeaches.carinventoryservice.SwaggerDocumentationConfig.java

@Configuration
@EnableSwagger2
public class SwaggerDocumentationConfig {

    @Value("${enable.swagger.plugin:true}")
    private boolean enableSwaggerPlugin;
  
    ApiInfo apiInfo() {

        return new ApiInfoBuilder()
            .title("Swagger Car Inventory Service")
            .description("Car Inventory Service")
            .license("MIT")
            .licenseUrl("https://opensource.org/licenses/MIT")
            .version("1.0.0")
            .contact(new Contact("Codeaches","https://codeaches.com", "pavan@codeaches.com"))
            .build();
    }

    @Bean
    public Docket customImplementation() {

      return new Docket(DocumentationType.SWAGGER_2)
          .useDefaultResponseMessages(false)
          .select()
          .apis(RequestHandlerSelectors.basePackage("com.codeaches.carinventoryservice"))
          .paths(PathSelectors.any())
          .build()
          .enable(enableSwaggerPlugin)
          .apiInfo(apiInfo());
    }
}

启动应用程序

启动 Spring Bootspring-boot-swagger-integration应用程序。

应用程序控制台日志

o.apache.catalina.core.StandardService   : Starting service [Tomcat]
org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.29]
o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
o.s.web.context.ContextLoader            : Root WebApplicationContext: initialization completed in 866 ms
pertySourcedRequestMappingHandlerMapping : Mapped URL path [/v2/api-docs] onto method [springfox.documentation.swagger2.web.Swagger2Controller#getDocumentation(String, HttpServletRequest)]
o.s.s.concurrent.ThreadPoolTaskExecutor  : Initializing ExecutorService 'applicationTaskExecutor'
d.s.w.p.DocumentationPluginsBootstrapper : Context refreshed
d.s.w.p.DocumentationPluginsBootstrapper : Found 1 custom documentation plugin(s)
s.d.s.w.s.ApiListingReferenceScanner     : Scanning for api listing references
o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
.SpringBootSwaggerIntegrationApplication : Started SpringBootSwaggerIntegrationApplication in 1.796 seconds (JVM running for 2.483)

Swagger UI 与我们的 rest 服务的基本集成到此结束。

在浏览器中启动 Swagger UI

让我们使用 URL http://localhost:8080/swagger-ui.html在浏览器中启动 Swagger UI

禁用 Swagger 用户界面

enable.swagger.plugin=false您可以通过在application.properties文件中更新来禁用 Swagger UI 。

Swagger REST API 文档

您可以在控制器代码中添加额外的文档，描述其每个操作、参数详细信息、输入和输出变量详细信息等。

所有这些细节都将显示在 Swagger UI 中。

com.codeaches.carinventoryservice.CarInventoryControllerInterface.java

public interface CarInventoryControllerInterface {

  @ApiOperation(value    = "Add a new car to the inventory", 
                nickname = "addCar", 
                response = String.class, 
                responseContainer = "String")
  @ApiResponses(value = {
                  @ApiResponse(code = 200, message = "Car Added Successfully", 
                               response = String.class, responseContainer = "String"),
                  @ApiResponse(code = 405, message = "Invalid input") })
  public String addCar(
      @ApiParam(value = "Car that needs to be added to the inventory", required = true) 
      @RequestBody(required = true) String car);

  @ApiOperation(value = "View cars in the inventory", nickname = "viewCars", response = Set.class, responseContainer = "Set<String>")
  @ApiResponses(value = {
      @ApiResponse(code = 200, message = "List of Cars returned successfully", response = Set.class, responseContainer = "Set<String>") })
  public Set<String> viewCars();
}

招摇用户界面

http://localhost:8080/swagger-ui.html#/car-inventory-controller/addCar

 

概括

我们将 Swagger UI 集成到 Spring Boot REST 服务应用程序的指南到此结束。

• 从 GitHub 下载代码