配置 Swagger 文档的自动生成

allway2

已于 2022-02-11 23:16:43 修改

阅读量2.3k

点赞数 1

文章标签： java 开发语言后端

于 2022-02-11 23:05:05 首次发布

本文链接：https://blog.csdn.net/allway2/article/details/122890239

版权

Swagger

Swagger 是一个开源工具。它围绕帮助开发人员设计、构建、记录和使用 RESTful API 的 OpenAPI 规范构建。它是 RESTful Web 服务最流行的 API 文档格式。它提供 JSON 和 UI 支持。JSON 可以作为机器可读的格式，Swagger-UI 用于可视化展示，人类只要浏览 API 文档就很容易理解。主要的 Swagger 工具有：

Swagger UI：它创建交互式 API 文档。
Swagger Editor：它是一个基于浏览器的编辑器，我们可以在其中编写 OpenAPI 规范。
Swagger Codegen：它生成服务器存根（API implementation stub），客户端库形成一个 OpenAPI 规范。

OpenAPI规范（以前称为 Swagger 规范）是 REST API 的 API 文档格式。一个开放的 API 文件允许我们描述我们的整个 API，包括：

可用端点 (/users)和每个端点上的操作(GET /users, POST /users)。
每个操作的操作参数。
身份验证方法。
联系方式、许可、使用期限等信息

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

第一步：打开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的类并编写以下代码。

Docket：一个构建器，旨在成为 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
@Configuration
//Enable Swagger
@EnableSwagger2
public class SwaggerConfig {
//creating bean
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2);
	}

//bean- docket
//swagger 2 
//All the paths
//all the APIs
}

第 3 步：运行应用程序。

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

它以 JSON 格式显示完整的文档，如下图所示。它不容易阅读和理解。Swagger 已将其提供给其他系统，例如提供 API 网关、API 缓存、API 文档等功能的 API 管理工具。