Proto: api_doc.proto

Package: apimanagement.gloo.solo.io

The ApiDoc resource represents the schema of an API served by a Destination (Service, ExternalService). ApiDocs are typically created by Gloo Platform discovery running on the agent in registered workload clusters, but you can also manually create an ApiDoc CR. The ApiDoc type is used to represent different types of API schema specification languages:

  • OpenAPI
  • gRPC
  • GraphQL

ApiDocReport

The report shows the resources that the ApiDoc selects after the it is successfully applied.

FieldDescription
workspaces(repeated ApiDocReport.WorkspacesEntry)

A list of workspaces in which the ApiDoc can be applied.
ownerWorkspace(string)

The name of the workspace that owns the Graqphql API schema.
servingDestinations(repeated common.gloo.solo.io.DestinationReference)

A list of destinations serving the API.

ApiDocReport.WorkspacesEntry

FieldDescription
key(string)

value(common.gloo.solo.io.Report)

ApiDocSpec

Specifications for the ApiDoc.

FieldDescription
openapi(ApiDocSpec.OpenAPISchema)

The OpenAPI schema specification language. Specify only one schema type.
grpc(ApiDocSpec.GrpcSchema)

The gRPC schema specification language. Specify only one schema type.
graphql(ApiDocSpec.GraphQLSchema)

The graphQL schema specification language. Specify only one schema type.
servedBy(repeated ServedBy)

The destinations that serve this API, if any.

ApiDocSpec.GraphQLSchema

Provide a schema definition in GraphQL SDL format. The GraphQL schema also has logging options for logging sensitive request-related information, and schema extension configuration such as custom type definitions. For more information about the different schema features, see the GraphQL documentation.

Example: In this GraphQL example for the Bookinfo sample app, a query type and object types are defined. For detailed information about the settings in this example, see Example GraphQL ApiDoc in the GraphQL integration documentation.

  apiVersion: apimanagement.gloo.solo.io/v2
kind: ApiDoc
metadata:
  annotations:
    cluster.solo.io/cluster: ""
  name: music-schema
  namespace: bookinfo
spec:
  graphql:
    schemaDefinition: |-
      schema {
        query: RootQuery
      }
      """A recording (studio/live album, EP, mixtape...)"""
      type Band {
        """A band unique identifier"""
        id: String!
        """Self-descriptive"""
        members: [Musician]
        """Self-descriptive"""
        name: String
      }
      """A recording (studio/live album, EP, mixtape...)"""
      type Musician {
        """A band unique identifier"""
        id: String!
        """List of instrument played"""
        instruments: [String]
        """Self-descriptive"""
        name: String
      }
      """A recording (studio/live album, EP, mixtape...)"""
      type Recording {
        """The artist credited for this recording"""
        artist: RecordingArtist
        """A recording unique identifier"""
        id: String!
        """Self-descriptive"""
        name: String
        """The recording release date"""
        releaseDate(
          """The output date format (default is 'DD-MM-YYY')"""
          dateFormat: String = "DD-MM-YYYY"
        ): String
      }
      union RecordingArtist = Band | Musician
      type RootQuery {
        artists: [RecordingArtist]
        recording(
          """id of recording"""
          id: String
        ): Recording
        """A list of all recordings"""
        recordings: [Recording]
      }
FieldDescription
schemaDefinition(string)

Required: The GraphQL schema definition. Root-level query and mutation types are supported, and you must define at least a query type.

ApiDocSpec.GrpcSchema

A complete gRPC schema describing the API.

Example: In this gRPC example for a basic user service app, the base64-encoded descriptor includes a set of fields that are defined for various queries, such as UserSearch and UserByCountry. For detailed information about the settings in this example, see gRPC schema in the GraphQL integration documentation.

  apiVersion: apimanagement.gloo.solo.io/v2
kind: ApiDoc
metadata:
  annotations:
    cluster.solo.io/cluster: ""
  name: grpc-schema
  namespace: bookinfo
spec:
  grpc:
    descriptors: CqIDChd1c2VyX3NlcnZpY2UvdXNlci5wcm90bxIEdXNlciKBAQoEVXNlchIdCgpmaXJzdF9uYW1lGAEgASgJUglmaXJzdE5hbWUSGwoJbGFzdF9uYW1lGAIgASgJUghsYXN0TmFtZRIaCgh1c2VybmFtZRgDIAEoCVIIdXNlcm5hbWUSIQoMY291bnRyeV9jb2RlGAUgASgJUgtjb3VudHJ5Q29kZSIoCgpVc2VyU2VhcmNoEhoKCHVzZXJuYW1lGAEgASgJUgh1c2VybmFtZSIyCg1Vc2VyQnlDb3VudHJ5EiEKDGNvdW50cnlfY29kZRgBIAEoCVILY291bnRyeUNvZGUiKQoFVXNlcnMSIAoFdXNlcnMYASADKAsyCi51c2VyLlVzZXJSBXVzZXJzMmwKC1VzZXJTZXJ2aWNlEicKB0dldFVzZXISEC51c2VyLlVzZXJTZWFyY2gaCi51c2VyLlVzZXISNAoQR2V0VXNlckJ5Q291bnRyeRITLnVzZXIuVXNlckJ5Q291bnRyeRoLLnVzZXIuVXNlcnNiBnByb3RvMw==
FieldDescription
descriptors(bytes)

Protobuf descriptors that represent the gRPC services provided by your API, encoded in base64. For more information, see the protobuf reference for FileDescriptorSet.

ApiDocSpec.OpenAPISchema

The YAML- or JSON-formatted OpenAPI v2 or v3 schema string to use for your API.

Example: For detailed information about the settings in this example, see Create your APIs in the Gloo Portal documentation.

  apiVersion: apimanagement.gloo.solo.io/v2
kind: ApiDoc
metadata:
  annotations:
    cluster.solo.io/cluster: ""
  name: customers-api-schema
  namespace: default
spec:
  openapi:
    inlineString: '{ "info": { "title": "Gloo Platform Portal API", "version": "1.0.0", "description": "Review the following reference documentation for the Gloo Platform portal APIs. Use these endpoints to manage user access to both the developer portal and the API resources exposed by the portal." }, "openapi": "3.0.0", "servers": [ { "url": "https://api.gloo-platform-portal.com/v1" } ], "paths": { "/login": { "get": { "description": "Logs user into the developer portal. This is the path that should be used as the callbackPath in the ExtAuthPolicy's OIDC configuration.", "operationId": "login", "security": [ { "identityToken": [ ] } ], "responses": { "200": { "description": "Successfully logged in" } }, "summary": "Logs user into the developer portal", "tags": [ "User" ] } }'
  servedBy:
  - destinationSelector:
      port:
        number: 8080
      selector:
        cluster: $CLUSTER_NAME
        name: app
        namespace: app
FieldDescription
inlineString(string)

The inline, YAML- or JSON-formatted, OpenAPI v2 or v3 schema.

ApiDocStatus

The status of the ApiDoc after it is applied to your Gloo environment.

Gloo reports the status of Gloo custom resources in several places, such as in logs, when describing the object in kubectl, or when viewing the object in the Gloo UI. Unlike other Gloo custom resources, ApiDocs can be both an input and output object. For example, you can manually create an ApiDoc (input), or Gloo can automatically create an ApiDoc during discovery or translation processes (output). As such, status for ApiDocs is disabled. Because the status is disabled, you cannot review statuses for ApiDocs in kubectl. Also, you might notice ApiDocs reported as unhealthy in the Gloo UI even though the ApiDocs work. To verify that your ApiDocs are healthy, you can follow the steps in the ApiDoc guide.

FieldDescription
common(common.gloo.solo.io.Status)

The state and workspace conditions of the applied resource.
ownerWorkspace(string)

The name of workspace that owns the APIDoc.
selectedServingDestinations(uint32)

Count of the destinations serving the API.

ServedBy

The destinations that serve this API, if any.

FieldDescription
destinationSelector(common.gloo.solo.io.DestinationSelector)

Specify the backing destination for your app, by label or by name. This destination matches the destinations that you later route to. Supported destinations are Kubernetes services, Gloo virtual destinations, and Gloo external services. This field is required when you manually create an ApiDoc for a service that serves an OpenAPI or gRPC schema.