配置自动生成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, 包括：

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

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

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

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

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

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

现在我们需要配置Swagger。

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

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

package com.srcmini.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。它显示了我们创建的服务的文档。

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