Skip to content
Last updated

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
  • 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:

# 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.

Swagger Codegen

Alternative client generation using Swagger Codegen:

# 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 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:

  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 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:

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

Learn more at openapi-typescript.

API Validation

Validate requests and responses against the OpenAPI specification:

Mock Server

Create a mock server for development and testing:

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

Learn more about Prism Mock Server.

Documentation Generation

Generate API documentation from the specification:

IDE Integration

VS Code

Install the OpenAPI (Swagger) Editor extension for:

  • Syntax highlighting
  • Auto-completion
  • Validation
  • Preview

JetBrains IDEs

Use the built-in OpenAPI Specifications plugin 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

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

Previous page
Next page