ApiDoc
ApiDoc API reference.
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.
Field | Description |
---|---|
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
Field | Description |
---|---|
key | (string ) |
value | (common.gloo.solo.io.Report ) |
ApiDocSpec
Specifications for the ApiDoc.
Field | Description |
---|---|
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]
}
Field | Description |
---|---|
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==
Field | Description |
---|---|
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
Field | Description |
---|---|
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.
Field | Description |
---|---|
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.
Field | Description |
---|---|
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. |