📜  配置Swagger文档的自动生成

📅  最后修改于: 2021-01-11 05:57:56             🧑  作者: Mango

配置自动生成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。它显示了我们创建的服务的文档。

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