# api.spec
## Module Functions
### Delete API Version <a name="delete"></a>
**API Endpoint**: `DELETE /api/{api_name}/spec/{api_version}`
#### Parameters
| Parameter | Required | Description | Example |
| ------------- | :------: | ----------- | ------------------------------------------------------ |
| `api_name` | ✓ | | `"my-project".to_string()` |
| `api_version` | ✓ | | `ApiVersion::VersionTypeEnum(VersionTypeEnum::Latest)` |
#### Example Snippet
```rust
let client = sideko_rest_api::SidekoClient::default()
.with_api_key_auth(&std::env::var("API_KEY").unwrap())
.with_cookie_auth(&std::env::var("API_KEY").unwrap());
let res = client
.api()
.spec()
.delete(sideko_rest_api::resources::api::spec::DeleteRequest {
api_name: "my-project".to_string(),
api_version: sideko_rest_api::models::ApiVersion::VersionTypeEnum(
sideko_rest_api::models::VersionTypeEnum::Latest,
),
})
.await;
```
### List API Versions <a name="list"></a>
**API Endpoint**: `GET /api/{api_name}/spec`
#### Parameters
| Parameter | Required | Description | Example |
| ---------- | :------: | ----------- | -------------------------- |
| `api_name` | ✓ | | `"my-project".to_string()` |
#### Example Snippet
```rust
let client = sideko_rest_api::SidekoClient::default()
.with_api_key_auth(&std::env::var("API_KEY").unwrap())
.with_cookie_auth(&std::env::var("API_KEY").unwrap());
let res = client
.api()
.spec()
.list(sideko_rest_api::resources::api::spec::ListRequest {
api_name: "my-project".to_string(),
})
.await;
```
#### Response
##### Type
Vec of [ApiSpec](/src/models/api_spec.rs)
##### Example
```rust
vec![ApiSpec {api: Api {created_at: "1970-01-01T00:00:00".to_string(), id: "3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a".to_string(), name: "my-api-spec-name".to_string(), version_count: 10}, created_at: "1970-01-01T00:00:00".to_string(), id: "3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a".to_string(), mock_server: ApiMockServer {enabled: true, url: "http://www.example.com".to_string()}, notes: "<p>This version includes a number of excellent improvements</p>".to_string(), version: "string".to_string()}]
```
### Get API Version <a name="get"></a>
**API Endpoint**: `GET /api/{api_name}/spec/{api_version}`
#### Parameters
| Parameter | Required | Description | Example |
| ------------- | :------: | ----------- | ------------------------------------------------------ |
| `api_name` | ✓ | | `"my-project".to_string()` |
| `api_version` | ✓ | | `ApiVersion::VersionTypeEnum(VersionTypeEnum::Latest)` |
#### Example Snippet
```rust
let client = sideko_rest_api::SidekoClient::default()
.with_api_key_auth(&std::env::var("API_KEY").unwrap())
.with_cookie_auth(&std::env::var("API_KEY").unwrap());
let res = client
.api()
.spec()
.get(sideko_rest_api::resources::api::spec::GetRequest {
api_name: "my-project".to_string(),
api_version: sideko_rest_api::models::ApiVersion::VersionTypeEnum(
sideko_rest_api::models::VersionTypeEnum::Latest,
),
})
.await;
```
#### Response
##### Type
[ApiSpec](/src/models/api_spec.rs)
##### Example
```rust
ApiSpec {api: Api {created_at: "1970-01-01T00:00:00".to_string(), id: "3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a".to_string(), name: "my-api-spec-name".to_string(), version_count: 10}, created_at: "1970-01-01T00:00:00".to_string(), id: "3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a".to_string(), mock_server: ApiMockServer {enabled: true, url: "http://www.example.com".to_string()}, notes: "<p>This version includes a number of excellent improvements</p>".to_string(), version: "string".to_string()}
```
### Get OpenAPI <a name="get_openapi"></a>
**API Endpoint**: `GET /api/{api_name}/spec/{api_version}/openapi`
#### Parameters
| Parameter | Required | Description | Example |
| ------------- | :------: | ----------- | ------------------------------------------------------ |
| `api_name` | ✓ | | `"my-project".to_string()` |
| `api_version` | ✓ | | `ApiVersion::VersionTypeEnum(VersionTypeEnum::Latest)` |
#### Example Snippet
```rust
let client = sideko_rest_api::SidekoClient::default()
.with_api_key_auth(&std::env::var("API_KEY").unwrap())
.with_cookie_auth(&std::env::var("API_KEY").unwrap());
let res = client
.api()
.spec()
.get_openapi(sideko_rest_api::resources::api::spec::GetOpenapiRequest {
api_name: "my-project".to_string(),
api_version: sideko_rest_api::models::ApiVersion::VersionTypeEnum(
sideko_rest_api::models::VersionTypeEnum::Latest,
),
})
.await;
```
#### Response
##### Type
[OpenApi](/src/models/open_api.rs)
##### Example
```rust
OpenApi {extension: OpenApiExtensionEnum::Json, is_config_valid: true, is_valid: true, openapi: "string".to_string(), validations: vec![Validation {message: "string".to_string(), severity: ValidationSeverityEnum::Error}]}
```
### Get Spec Stats <a name="get_stats"></a>
**API Endpoint**: `GET /api/{api_name}/spec/{api_version}/stats`
#### Parameters
| Parameter | Required | Description | Example |
| ------------- | :------: | ----------- | ------------------------------------------------------ |
| `api_name` | ✓ | | `"my-project".to_string()` |
| `api_version` | ✓ | | `ApiVersion::VersionTypeEnum(VersionTypeEnum::Latest)` |
#### Example Snippet
```rust
let client = sideko_rest_api::SidekoClient::default()
.with_api_key_auth(&std::env::var("API_KEY").unwrap())
.with_cookie_auth(&std::env::var("API_KEY").unwrap());
let res = client
.api()
.spec()
.get_stats(sideko_rest_api::resources::api::spec::GetStatsRequest {
api_name: "my-project".to_string(),
api_version: sideko_rest_api::models::ApiVersion::VersionTypeEnum(
sideko_rest_api::models::VersionTypeEnum::Latest,
),
})
.await;
```
#### Response
##### Type
[ApiSpecStats](/src/models/api_spec_stats.rs)
##### Example
```rust
ApiSpecStats {authenticated_methods: 123, authentication_schemes: vec!["string".to_string()], endpoints: 123, lint_errors: ApiSpecStatsLintErrors {incorrect_examples: vec![LintErrorDetails {location: Some("request-body".to_string()), message: Some("the object is missing a required property".to_string()), method: "GET".to_string(), path: "/api/v1/path".to_string()}], incorrect_paths: vec!["string".to_string()], missing_operation_ids: vec![LintErrorDetails {location: Some("request-body".to_string()), message: Some("the object is missing a required property".to_string()), method: "GET".to_string(), path: "/api/v1/path".to_string()}]}, methods: 123, public_methods: 123, response_codes: vec![123]}
```
### Update API Version <a name="patch"></a>
**API Endpoint**: `PATCH /api/{api_name}/spec/{api_version}`
#### Parameters
| Parameter | Required | Description | Example |
| --------------------- | :------: | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `api_name` | ✓ | | `"my-project".to_string()` |
| `api_version` | ✓ | | `ApiVersion::VersionTypeEnum(VersionTypeEnum::Latest)` |
| `allow_lint_errors` | ✗ | Allow API spec to be updated with a new OpenAPI spec even if it has linting errors | `true` |
| `mock_server_enabled` | ✗ | Enable a public mock server requests for this API Specification | `true` |
| `notes` | ✗ | Text field to add any notes (comments, changelog, etc.) relevant to the version in html format | `"<p>This version includes a number of excellent improvements</p>".to_string()` |
| `openapi` | ✗ | An OpenAPI specification in YAML or JSON | `UploadFile::from_path("uploads/openapi.yaml").unwrap()` |
| `version` | ✗ | Semantic Version of the API | `"string".to_string()` |
#### Example Snippet
```rust
let client = sideko_rest_api::SidekoClient::default()
.with_api_key_auth(&std::env::var("API_KEY").unwrap())
.with_cookie_auth(&std::env::var("API_KEY").unwrap());
let res = client
.api()
.spec()
.patch(sideko_rest_api::resources::api::spec::PatchRequest {
notes: Some(
"<p>This version includes a number of excellent improvements</p>"
.to_string(),
),
openapi: Some(
sideko_rest_api::UploadFile::from_path("uploads/openapi.yaml").unwrap(),
),
api_name: "my-project".to_string(),
api_version: sideko_rest_api::models::ApiVersion::VersionTypeEnum(
sideko_rest_api::models::VersionTypeEnum::Latest,
),
..Default::default()
})
.await;
```
#### Response
##### Type
[ApiSpec](/src/models/api_spec.rs)
##### Example
```rust
ApiSpec {api: Api {created_at: "1970-01-01T00:00:00".to_string(), id: "3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a".to_string(), name: "my-api-spec-name".to_string(), version_count: 10}, created_at: "1970-01-01T00:00:00".to_string(), id: "3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a".to_string(), mock_server: ApiMockServer {enabled: true, url: "http://www.example.com".to_string()}, notes: "<p>This version includes a number of excellent improvements</p>".to_string(), version: "string".to_string()}
```
### Create API Version <a name="create"></a>
**API Endpoint**: `POST /api/{api_name}/spec`
#### Parameters
| Parameter | Required | Description | Example |
| --------------------- | :------: | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `api_name` | ✓ | | `"my-project".to_string()` |
| `openapi` | ✓ | An OpenAPI specification in YAML or JSON | `UploadFile::from_path("uploads/openapi.yaml").unwrap()` |
| `allow_lint_errors` | ✗ | Allow API spec to be created even if it has linting errors | `true` |
| `mock_server_enabled` | ✗ | Enable a public mock server requests for this API Specification | `true` |
| `notes` | ✗ | Text field to add any notes (comments, changelog, etc.) relevant to the version in html format | `"<p>This version includes a number of excellent improvements</p>".to_string()` |
| `version` | ✗ | | `VersionOrBump::VersionBumpEnum(VersionBumpEnum::Auto)` |
#### Example Snippet
```rust
let client = sideko_rest_api::SidekoClient::default()
.with_api_key_auth(&std::env::var("API_KEY").unwrap())
.with_cookie_auth(&std::env::var("API_KEY").unwrap());
let res = client
.api()
.spec()
.create(sideko_rest_api::resources::api::spec::CreateRequest {
notes: Some(
"<p>This version includes a number of excellent improvements</p>"
.to_string(),
),
openapi: sideko_rest_api::UploadFile::from_path("uploads/openapi.yaml")
.unwrap(),
api_name: "my-project".to_string(),
..Default::default()
})
.await;
```
#### Response
##### Type
[ApiSpec](/src/models/api_spec.rs)
##### Example
```rust
ApiSpec {api: Api {created_at: "1970-01-01T00:00:00".to_string(), id: "3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a".to_string(), name: "my-api-spec-name".to_string(), version_count: 10}, created_at: "1970-01-01T00:00:00".to_string(), id: "3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a".to_string(), mock_server: ApiMockServer {enabled: true, url: "http://www.example.com".to_string()}, notes: "<p>This version includes a number of excellent improvements</p>".to_string(), version: "string".to_string()}
```