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
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)Unsupported: The GraphQL integration is no longer supported. The graphQL schema specification language. Specify only one schema type. |
servedBy | (repeated ServedBy)The destinations that serve this API, if any. |
ApiDocSpec.GraphQLSchema
Unsupported: The GraphQL integration is no longer supported.
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.
| 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
Unsupported: The GraphQL integration is no longer supported.
A complete gRPC schema describing the API.
| 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.
| 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. |