# OpenAPI Specification

The Vilna API is fully documented using OpenAPI 3.1 specification, enabling automatic client generation and integration with popular API tools.

## Specification Access

The OpenAPI specification is available at:

- **API Reference:** [/apis/spec.yaml](/apis/spec)
- **Format:** OpenAPI 3.1
- **Schema:** JSON Schema Draft 2020-12


## Client Generation

### OpenAPI Generator

Generate client libraries for your preferred programming language using [OpenAPI Generator](https://openapi-generator.tech/):


```bash
# Install OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate a client (example for Python)
openapi-generator-cli generate \
  -i path/to/spec.yaml \
  -g python \
  -o ./vilna-python-client
```

Supported languages include Python, JavaScript, TypeScript, Go, Java, C#, PHP, Ruby, and [many more](https://openapi-generator.tech/docs/generators).

### Swagger Codegen

Alternative client generation using [Swagger Codegen](https://swagger.io/tools/swagger-codegen/):


```bash
# Generate a client (example for Java)
swagger-codegen generate \
  -i path/to/spec.yaml \
  -l java \
  -o ./vilna-java-client
```

## API Testing Tools

### Swagger UI

Use [Swagger UI](https://swagger.io/tools/swagger-ui/) to visualize and interact with the API:

1. Import the OpenAPI specification
2. Explore available endpoints
3. Test API calls directly from the browser
4. View request/response schemas


### Postman

Import the specification into [Postman](https://www.postman.com/):

1. Open Postman
2. Click "Import" → "File"
3. Select the OpenAPI specification file
4. Postman will create a collection with all endpoints
5. Configure your API key in the collection variables


### Insomnia

Use [Insomnia](https://insomnia.rest/) for API debugging:

1. Create a new Document in Insomnia
2. Import the OpenAPI specification
3. Configure authentication
4. Test endpoints with auto-completion


## Code Generation Tools

### TypeScript Types

Generate TypeScript types from the OpenAPI specification:


```bash
# Using openapi-typescript
npx openapi-typescript path/to/spec.yaml --output vilna-types.ts
```

Learn more at [openapi-typescript](https://github.com/drwpow/openapi-typescript).

### API Validation

Validate requests and responses against the OpenAPI specification:

- **Node.js:** [express-openapi-validator](https://github.com/cdimascio/express-openapi-validator)
- **Python:** [openapi-core](https://github.com/p1c2u/openapi-core)
- **Go:** [kin-openapi](https://github.com/getkin/kin-openapi)


## Mock Server

Create a mock server for development and testing:


```bash
# Using Prism
npm install -g @stoplight/prism-cli
prism mock path/to/spec.yaml
```

Learn more about [Prism Mock Server](https://stoplight.io/open-source/prism).

## Documentation Generation

Generate API documentation from the specification:

- **ReDoc:** [ReDoc](https://github.com/Redocly/redoc)
- **Slate:** [widdershins](https://github.com/Mermade/widdershins) + [Slate](https://github.com/slatedocs/slate)
- **MkDocs:** [mkdocs-openapi](https://github.com/blueswen/mkdocs-openapi)


## IDE Integration

### VS Code

Install the [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) extension for:

- Syntax highlighting
- Auto-completion
- Validation
- Preview


### JetBrains IDEs

Use the built-in [OpenAPI Specifications plugin](https://www.jetbrains.com/help/idea/openapi.html) for:

- Code generation
- Endpoint navigation
- Request testing


## Best Practices

1. **Version Control:** Always specify the API version when generating clients
2. **Validation:** Validate your implementation against the specification
3. **Updates:** Regenerate clients when the API specification is updated
4. **Custom Templates:** Use custom templates for generated code when needed
5. **Testing:** Use the specification for contract testing


## Additional Resources

- [OpenAPI Initiative](https://www.openapis.org/)
- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
- [JSON Schema](https://json-schema.org/)
- [API Tools Directory](https://openapi.tools/)


*The OpenAPI specification is the source of truth for the Vilna API. All tools and generated clients should be based on this specification.*