> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# vydev/service-documentation

Publish documentation about your service to developer.portal.vydev.io!


## Commands

### convert-yaml

Upload the artifact to the respective path in the artifact bucket.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `destination-file` | string |  | The full path of where to find the file to upload. |
| `source-file` | string |  | The full path of where to find the file to upload. |

### convert-yaml-and-upload-artifact

Convert if yaml. Upload the artifact to the respective path in the artifact bucket.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `artifact-bucket` | string |  | The bucket to upload artifacts to |
| `file-name` | string |  | The name of the file to upload to S3 |
| `service-name` | string |  | The name of the service to be shown in the API portal. |
| `source-file` | string |  | The full path of where to find the file to upload. |

### persist-api-spec

Persist the API Specification content to a database for its metadata.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-spec-type` | string | openapi | The type of API spec being uploaded. |
| `persist-url` | string |  | The domain of the persist API |
| `region` | string | eu-west-1 | The AWS region to use for the API call. |
| `service-name` | string |  | The name of the service to be shown in the API portal. |

### process-graphql-specification

Processes the GraphQL Schema into multiple .md files for the API Portal

| Parameter | Type | Default | Description |
|---|---|---|---|
| `process-graphql-api-url` | string | graphql-schema-to-markdown.common-services.vydev.io | The URL of the API Gateway for GraphQL conversion. |
| `region` | string | eu-west-1 | The AWS region to use for the API call. |
| `service-name` | string |  | The name of the service to be shown in the API portal. |

### upload-and-validate-apiportal-config

Uploads the API Portal configuration to the artifact bucket, and verifies its content.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `artifact-bucket` | string |  | The bucket to upload the config file to |
| `region` | string | eu-west-1 | The AWS region to use for the API call. |
| `service-name` | string |  | The name of the service to be shown in the API portal. |
| `source-file` | string |  | The full path of where to find the API Portal configuration to upload. |
| `validator-url` | string |  | The domain of the validator API |

### upload-artifact

Upload the artifact to the respective path in the artifact bucket.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `artifact-bucket` | string |  | The bucket to upload artifacts to |
| `file-extension` | string | json | The file extension of the file to upload |
| `file-name` | string |  | The name of the file to upload |
| `service-name` | string |  | The name of the service to be shown in the API portal. |
| `source-file` | string |  | The full path of where to find the file to upload. |

## Jobs

### push-api-config-and-spec

LEGACY: Use `push-api-spec` instead. Converts the API spec to JSON and uploads it to the artifact bucket.
Supports OpenAPI, AsyncAPI, and GraphQL API specs.
Additionally, uploads the API Portal configuration to the artifact bucket, and verifies its content.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `apiportal-source-file` | string | .deployment/apiportal.yaml | The full path of where to find the API Portal specification to upload. |
| `artifact-bucket` | string | 727646359971-api-portal-artifacts | The bucket to upload the config file to |
| `asyncapi-path` | string |  | Path to your Async API spec. |
| `graphql-path` | string |  | Path to your GraphQL API spec. |
| `openapi-path` | string |  | Path to your Open API spec. |
| `process-graphql-api-url` | string | graphql-schema-to-markdown.common-services.vydev.io | The URL of the API for GraphQL conversion. |
| `service-name` | string |  | The name of the service to be shown in the API portal. |
| `validator-url` | string | api-reference-validator.common-services.vydev.io | The domain of the validator API |
| `workspace` | string |  | Attach to an existing workspace that has the API spec |

### push-api-spec

Converts the API spec to JSON and uploads it to the artifact bucket.
Supports OpenAPI, AsyncAPI, and GraphQL API specs.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `artifact-bucket` | string | 727646359971-api-portal-artifacts | The bucket to upload the config file to |
| `asyncapi-path` | string |  | Path to your Async API spec. |
| `graphql-path` | string |  | Path to your GraphQL API spec. |
| `openapi-path` | string |  | Path to your Open API spec. |
| `persist-url` | string | api-reference-persist.common-services.vydev.io | The domain of the persist API |
| `process-graphql-api-url` | string | graphql-schema-to-markdown.common-services.vydev.io | The URL of the API for GraphQL conversion. |
| `service-name` | string |  | The name of the service to be shown in the API portal. |
| `workspace` | string |  | Attach to an existing workspace that has the API spec |

## Executors

### aws-cli

AWS CLI and some other tools

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | latest |  |

## Examples

### combined-job-example

A simple use case where we send an api spec to the API portal.


```yaml
version: '2.1'
orbs:
  documentation: vydev/service-documentation@<version>
workflows:
  build-and-deploy:
    jobs:
      - documentation/push-api-config-and-spec:
          context:
            - team-context
          openapi-path: path/to/your/openapi.yaml
          service-name: my-service
```

### multiple-api-docs-example

A use case where we can send multiple types of api spec to the API portal.


```yaml
version: '2.1'
orbs:
  documentation: vydev/service-documentation@<version>
workflows:
  build-and-deploy:
    jobs:
      - documentation/push-api-config-and-spec:
          asyncapi-path: path/to/your/asyncapi.yaml
          context:
            - team-context
          graphql-path: path/to/your/graphql.schema
          openapi-path: path/to/your/openapi.yaml
          service-name: my-service
```