Apigee · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Apigee API Hub Specs API

8 actions 8 updates phrasing extends openapi/apigee-specs-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for Apigee's API. It is a proposal applied on top of the contract, not a document Apigee publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 8

$.info
$.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs'].get
$.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs'].post
$.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}'].get
$.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}'].delete
$.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}'].patch
$.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}:getContents'].get
$.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}:lint'].post

OpenAPI Overlay

Raw ↑ 
# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Apigee API Hub Specs API
  version: 1.0.0
extends: openapi/apigee-specs-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs'].get
  update:
    x-apievangelist-phrasing:
      intent: List specs for an API Hub version
      effect: read
      questions:
      - What OpenAPI or Protocol Buffer specs are attached to an API version in API Hub?
      - Can I filter the specs listed for an API Hub version?
      instructions:
      - text: List API Hub specs for API {apiId} version {versionId} in project {projectId}, location {locationId}.
        slots:
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      - text: Show API Hub specs of API {apiId} version {versionId} in {projectId}/{locationId} matching {filter}.
        slots:
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a spec to an API Hub version
      effect: write
      questions:
      - How do I attach an OpenAPI document to an API version in API Hub?
      - Can I choose the parsing mode when adding a spec to API Hub?
      instructions:
      - text: Create API Hub spec {specId} for API {apiId} version {versionId} in project {projectId}, location {locationId}.
        slots:
          specId: query.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      - text: Attach spec {specId} of type {specType} to API Hub API {apiId} version {versionId} in {projectId}/{locationId}.
        slots:
          specId: query.specId
          specType: requestBody.specType
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an API Hub spec's metadata
      effect: read
      questions:
      - What spec type and parsing mode does an API Hub spec use?
      - Where do I see the stored lint results for one spec in API Hub?
      instructions:
      - text: Get API Hub spec {specId} of API {apiId} version {versionId} in project {projectId}, location {locationId}.
        slots:
          specId: path.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      - text: Show the metadata and lint response for API Hub spec {specId}, API {apiId} version {versionId}, in {projectId}/{locationId}.
        slots:
          specId: path.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a spec from API Hub
      effect: destructive
      questions:
      - Is there a way to drop an outdated spec from an API version in API Hub?
      - Can I delete a single spec without deleting its API version in API Hub?
      instructions:
      - text: Delete API Hub spec {specId} from API {apiId} version {versionId} in project {projectId}, location {locationId}.
        slots:
          specId: path.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      - text: Remove spec {specId} from API Hub API {apiId} version {versionId} in {projectId}/{locationId}.
        slots:
          specId: path.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an API Hub spec
      effect: write
      questions:
      - How do I replace the contents of a spec already in API Hub?
      - Can I change only some fields of an API Hub spec?
      instructions:
      - text: Update API Hub spec {specId} of API {apiId} version {versionId} in project {projectId}, location {locationId} with mask {updateMask}.
        slots:
          specId: path.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
          updateMask: query.updateMask
      - text: Set the display name of API Hub spec {specId} to {displayName} for API {apiId} version {versionId} in {projectId}/{locationId}, mask {updateMask}.
        slots:
          specId: path.specId
          displayName: requestBody.displayName
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
          updateMask: query.updateMask
      method: generated
      generated: '2026-10-01'
- target: $.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}:getContents'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the raw contents of an API Hub spec
      effect: read
      questions:
      - How do I download the actual OpenAPI or proto file behind an API Hub spec?
      - Can I read the raw definition file for a spec in API Hub?
      instructions:
      - text: Get the raw file contents of API Hub spec {specId} for API {apiId} version {versionId} in project {projectId}, location {locationId}.
        slots:
          specId: path.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      - text: Download the definition file of spec {specId}, API Hub API {apiId} version {versionId}, from {projectId}/{locationId}.
        slots:
          specId: path.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/projects/{projectId}/locations/{locationId}/apis/{apiId}/versions/{versionId}/specs/{specId}:lint'].post
  update:
    x-apievangelist-phrasing:
      intent: Lint an API Hub spec
      effect: write
      questions:
      - Can API Hub check my spec against style and correctness rules?
      - How do I get lint warnings and errors for a spec in API Hub?
      instructions:
      - text: Lint API Hub spec {specId} of API {apiId} version {versionId} in project {projectId}, location {locationId}.
        slots:
          specId: path.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      - text: Run style and correctness checks on spec {specId} for API Hub API {apiId} version {versionId} in {projectId}/{locationId}.
        slots:
          specId: path.specId
          apiId: path.apiId
          versionId: path.versionId
          projectId: path.projectId
          locationId: path.locationId
      method: generated
      generated: '2026-10-01'