swagger和openAPI: OpenAPI扩展

OpenAPI扩展 扩展或供应商扩展是自定义属性x-,例如x-logo。它们可以用来描述标准OpenAPI规范没有涉及的额外功能。许多支持OpenAPI的API相关产品都使用扩展来记录自己的属性,例如Amazon API Gateway,ReDoc,APIMatic等。 API规范的根级别和以下位置支持扩展: info ...阅读更多

Posted on

swagger和openAPI: 用标签分组操作

用标签分组操作 您可以tags为每个API操作分配一个列表。标记的操作可能由工具和库以不同方式处理。例如,Swagger UI用于tags对显示的操作进行分组。 paths: /pet/findByStatus: get: summary: Finds pets by Status tags: - pets ... / ...阅读更多

Posted on

swagger和openAPI: API通用信息

API通用信息 将API的一般信息纳入规范被认为是一种很好的做法:版本号,许可证说明,联系人数据,文档链接等。我们特别建议为公共可用的API执行此操作; 因为这可以增加用户对服务的信心,贵公司提供。 要指定API元数据,请使用顶级info对象的属性: openapi: 3.0.0 info: # You applica ...阅读更多

Posted on

swagger和openAPI: 使用$ ref

使用$ ref 在记录API时,通常会使用跨若干API资源使用的某些功能。在这种情况下,您可以为这些元素创建一个片段,以便在需要时多次使用它们。 借助OpenAPI 3.0,您可以引用托管在任何位置的定义。它可以是同一台服务器,也可以是另一台服务器 - 例如GitHub,SwaggerHub等等。 要引用定义,请使用$ ...阅读更多

Posted on

swagger和openAPI: 组件部分

组件部分 通常,多个API操作具有一些通用参数或返回相同的响应结构。为避免代码重复,您可以将常用定义放置在全局  components部分中并使用它们进行引用$ref。 在下面的示例中,用户对象的重复定义被替换为单个组件以及对该组件的引用。 之前: paths: /users/{userId}: get: summar ...阅读更多

Posted on

swagger和openAPI: 回调

回调 在OpenAPI 3规范中,您可以定义回调 - 异步,带外请求,您的服务将响应某些事件发送给其他服务。这可以帮助您改善API向客户提供的工作流程。 回调的一个典型例子是订阅功能 - 用户订阅您服务的某些事件,并在发生此事件或事件时收到通知。例如,电子商店可以在每次购买时向经理发送通知。这些通知将是“带外”的,也就 ...阅读更多

Posted on

swagger和openAPI: 链接

链接是OpenAPI 3.0的新功能之一。使用链接,可以描述一个操作返回的各种值如何用作其他操作的输入。这样,链接提供了操作之间的已知关系和遍历机制。 链接的概念有点类似于超媒体,但OpenAPI链接不需要实际响应中的链接信息。 何时使用链接? 考虑“创建用户”操作: POST /users HTTP/1.1 Host ...阅读更多

Posted on

swagger和openAPI: Cookie认证

Cookie认证 Cookie认证使用HTTP cookie来认证客户端请求并维护会话信息。它的工作原理如下: 客户端向服务器发送登录请求。 在成功登录时,服务器响应包括包含cookie名称,值,到期时间和一些其他信息的Set-Cookie标头。以下是一个设置名为cookie的示例JSESSIONID: Set-Coo ...阅读更多

Posted on

swagger和openAPI: OpenID Connect发现

OpenID Connect发现 OpenID Connect(OIDC)是构建于 OAuth 2.0协议之上的一个身份层,由一些OAuth 2.0提供程序(例如Google和Azure Active Directory)提供支持。它定义了一种登录流程,它使客户端应用程序能够对用户进行身份验证,并获取有关该用户的信息( ...阅读更多

Posted on

swagger和openAPI: OAuth 2.0

OAuth 2.0 OAuth 2.0是一种授权协议,它允许API客户端有限访问Web服务器上的用户数据。GitHub,Google和Facebook API特别使用它。OAuth依赖称为流的身份验证方案,它允许资源所有者(用户)共享来自资源服务器的受保护内容而不共享其凭据。为此,OAuth 2.0服务器会发出访问令牌 ...阅读更多

Posted on

swagger和openAPI: 承载认证

承载认证 承载认证(也称为令牌认证)是一种HTTP认证方案,涉及称为承载令牌的安全令牌。“承载认证”的名称可以理解为“授予访问该令牌的承载者”。 不记名令牌是一种神秘的字符串,通常由服务器响应登录请求而生成。Authorization当向受保护资源发出请求时,客户端必须在标头中发送该令牌: Authorization: ...阅读更多

Posted on

swagger和openAPI: API密钥

API密钥 一些API使用API​​密钥进行授权。API密钥是客户在进行API调用时提供的令牌。密钥可以在查询字符串中发送: GET /something?api_key=abcdef12345 或作为请求标题: GET /something HTTP/1.1 X-API-Key: abcdef12345 或者作为一个 ...阅读更多

Posted on