Referindo-se a uma extensão em uma definição de API

Editar online

Para fazer referência a uma extensão OpenAPI em seu arquivo YAML (ou JSON) de definição de API, inclua uma extensions chave sob x-ibm-configuration.

Antes de Iniciar

Adicione a extensão ` OpenAPI ` a todos os catálogos nos quais a API será publicada, importando seu arquivo de definição; para mais detalhes, consulte Trabalhando com extensões ` OpenAPI `. Se o catálogo de destino não contiver a extensão OpenAPI , as tentativas de publicar a API nele falharão.

Sobre essa tarefa

O exemplo a seguir mostra um arquivo de definição de extensão que define uma filial do banco no formato YAML:

extension: '1.0.0'

info: 
   title: Banking services
   name: banking
   version: 1.0.0
   description: Banking extensions
   contact: 
     name: IBM API Connect
     url: https://apiconnect.ibm.com/
     email: myname@ibm.com

properties:
  title: "Branch"
  type: "object"
  properties: 
    Branch type: 
      type: "string"
      enum: 
        - "ATM"
        - "Walk in"
    location: 
      type: "object"
      title: "Location"
      properties: 
        city: 
          type: "string"
          default: "San Francisco"
        state: 
          type: "string"
          default: "CA"
        citystate: 
          type: "string"
          description: "This is generated automatically from the previous two fields"
          template: "{{city}}, {{state}}"
          watch: 
            city: "location.city"
            state: "location.state"
  required:
    - Branch type

A tabela a seguir fornece mais informações sobre os campos disponíveis ao criar uma extensão de API.

Tabela 1. Descrição dos campos
Campo	Descrição	Obrigatório	Exemplo
`version`	Número da versão da extensão Observação: O `version` campo deve seguir o esquema de `version.release.modification` numeração de versões.	True	`1.0.0`
`title`	Título da extensão Observação: Os campos `title` `name` e devem ser curtos para que possam ser exibidos na interface do usuário do API Manager.	True	Serviço bancário
`name`	Nome abreviado da extensão Observação: O `name` campo deve conter uma única palavra e apenas caracteres alfanuméricos, traço e sublinhado.	True	financeiro
`description`	Breve descrição da extensão	Não	Extensões bancárias
`termsofservice`	Termos de serviço da extensão	Não	Termos de Serviço
`license.name`	Nome da licença	Não	IBM API Connect
`license.URL`	URL relativo à licença	Não	https://apiconnect.ibm.com/
`contact.name`	Nome do contato	Não	myname@ibm.com
`contact.URL`	URL para entrar em contato com a organização	Não	https://www.example.com/support
`contact.email`	E-mail para entrar em contato com a organização	Não	support@example.com
`gateways`	Lista de gateways com os quais a extensão pode ser usada Observação: O `gateways` campo é opcional, mas, se for incluído, deve indicar os tipos de gateways com os quais a extensão pode ser utilizada.	Não	`datapower-api-gateway` `datapower-gateway`
`properties`	As propriedades personalizadas a serem incluídas na extensão OpenAPI.	Não	O `properties` campo pode ser personalizado para incluir quaisquer propriedades válidas de ` OpenAPI `. `properties: title: "Branch" type: "object" properties: Branch type: type: "string" enum: - "ATM" - "Walk in"`

Procedimento

Para habilitar o uso de extensões personalizadas em uma definição de API, siga estas etapas:

Edite o arquivo YAML de definição de API e inclua a referência. Por exemplo:
```
x-ibm-configuration:
      .
      .
      .
  extensions:
    banking: 1.0.0
```
Em seu arquivo de definição de API, inclua uma propriedade cujo nome deve começar com x- e referencie o nome da extensão criada. Especifique os valores das propriedades que foram definidas no arquivo YAML de extensão OpenAPI .
O exemplo a seguir usa a extensão banking:
```
      .
      .
      .
x-banking:
  Branch type: ATM
  location:
    city: San Francisco
    state: CA
    citystate: 'San Francisco, CA'
  
```