配置自动生成Swagger文档

昂首阔步

Swagger是一种开源工具。它围绕OpenAPI规范构建，该规范可帮助开发人员设计，构建，记录和使用RESTful API。它是RESTful Web服务的最流行的API文档格式。它同时提供JSON和UI支持。 JSON可以用作机器可读格式，而Swagger-UI则用于可视化显示，人们只要浏览API文档即可轻松理解。 Swagger的主要工具是：

• Swagger UI：它创建交互式API文档。
• Swagger编辑器：这是一个基于浏览器的编辑器，我们可以在其中编写OpenAPI规范。
• Swagger Codegen：它生成服务器存根(API实现存根)，并且客户端库形成OpenAPI规范。

OpenAPI规范(以前称为Swagger规范)是REST API的API文档格式。 Open API文件使我们能够描述整个API，包括：

• 可用端点(/用户)和每个端点上的操作(GET /用户，POST /用户)。
• 每个操作的操作参数。
• 身份验证方法。
• 联系信息，许可，使用条款和其他信息

让我们为RESTful服务生成Swagger文档。

步骤1：打开pom.xml并添加springfox-swagger2依赖项。

    io.springfox
    springfox-swagger2
    2.9.2

添加另一个依赖项springfox-swagger-ui

    io.springfox
    springfox-swagger-ui
    2.9.2

现在我们需要配置Swagger。

步骤2：创建一个名称为SwaggerConfig.java的类，并编写以下代码。

资料夹：一个构建器，旨在成为swagger-Spring MVC框架的主要接口。 Docket提供了明智的默认设置和便捷的配置方法。

package com.javatpoint.server.main;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
//Enable Swagger
@EnableSwagger2
public class SwaggerConfig 
{
//creating bean
@Bean
public Docket api()
{
//creating constructor of Docket class that accepts parameter DocumentationType
return new Docket(DocumentationType.SWAGGER_2);
}
}

步骤3：运行应用程序。

步骤4：打开浏览器并输入URI http：// localhost：8080 / v2 / api-docs

它以JSON格式显示了完整的文档，如下图所示。它不是很容易阅读和理解。 Swagger提供了它可以在其他系统中使用，例如API管理工具，它提供了API网关，API缓存，API文档等功能。

如果我们想与客户共享Web服务的文档，则可以共享此JSON文件。

现在，在浏览器中键入URI http：// localhost：8080 / swagger-ui.html。它显示了我们创建的服务的文档。

我们还可以扩展服务以查看服务中存在哪些操作。在下图中，我们扩展了用户资源服务。