# @push.rocks/smartswagger
a swagger tookit for working with swagger files

## Install
To install `@push.rocks/smartswagger`, use npm:
```bash
npm install @push.rocks/smartswagger --save
```
This will add `@push.rocks/smartswagger` to your project's dependencies.

## Usage
`@push.rocks/smartswagger` provides a comprehensive toolkit for working with Swagger (now known as OpenAPI) files in a TypeScript and ESM syntax environment. Below, we'll dive into several scenarios covering how you can utilize `@push.rocks/smartswagger` effectively in your projects.

### Creating a New `Smartswagger` Instance
Start by creating a new instance of `Smartswagger`. You can do this from a URL pointing to a Swagger file or by manually specifying Swagger document properties.

#### From an External Swagger File URL
```typescript
import { Smartswagger } from '@push.rocks/smartswagger';

async function loadSwaggerFromUrl() {
  const swaggerInstance = await Smartswagger.createFromUrl('https://example.com/path/to/swagger.json');
  // Now you have a Smartswagger instance created from an external Swagger file
}
```

#### Creating a New Swagger Document
```typescript
import { Smartswagger } from '@push.rocks/smartswagger';

async function createNewSwaggerDoc() {
  const swaggerInstance = await Smartswagger.createNew('My API Documentation');
  // Now you have a new Smartswagger instance with basic setup
}
```

### Merging Swagger Documents
One of the powerful features of `@push.rocks/smartswagger` is the ability to merge multiple Swagger documents into a single one. This is particularly useful when working with microservices or splitting your API documentation across several files for better organization.

#### Merging Documents from URLs
Suppose you have several Swagger documents for different parts of your API hosted at various URLs. You can merge them into a single document like so:

```typescript
import { Smartswagger } from '@push.rocks/smartswagger';

async function mergeDocuments() {
  const mainApiDoc = await Smartswagger.createNew('Combined API Documentation');
  
  await mainApiDoc.mergeManyDocumentsFromUrl([
    { url: 'https://example.com/path/to/users/api/swagger.json' },
    { url: 'https://example.com/path/to/products/api/swagger.json', basePath: '/products' },
    // Include as many as needed
  ]);
  
  // Now mainApiDoc contains a merged version of all specified Swagger documents
}
```

### Adding Servers and Security Schemes
You can add servers and security schemes to your Swagger document as follows:

#### Adding a Server
```typescript
import { Smartswagger } from '@push.rocks/smartswagger';

async function addServer() {
  const swaggerInstance = await Smartswagger.createNew();
  
  await swaggerInstance.addServer({
    url: 'https://api.example.com/',
    description: 'Main API Server'
  });
  
  // Your Swagger instance now includes the server information
}
```

#### Merging Security Schemes to Routes
```typescript
import { Smartswagger, openapiTypes } from '@push.rocks/smartswagger';

async function addSecuritySchemes() {
  const swaggerInstance = await Smartswagger.createNew();
  
  const securityScheme: openapiTypes.OpenAPIV3.SecuritySchemeObject = {
    type: 'http',
    scheme: 'bearer',
    bearerFormat: 'JWT'
  };

  swaggerInstance.mergeComponentToRoutes({ includeGlobArray: ['**'], excludeGlobArray: [] }, { securitySchemes: { bearerAuth: securityScheme } });
  
  // Now, all routes in your Swagger document include the specified security scheme
}
```

### Integrating with Express and Serving Your API Documentation
`@push.rocks/smartswagger` integrates seamlessly with Express, allowing you to serve your API documentation using Swagger UI or ReDoc.

```typescript
import { Smartswagger } from '@push.rocks/smartswagger';
import * as smartexpress from '@pushrocks/smartexpress';

async function serveSwaggerUI() {
  const swaggerInstance = await Smartswagger.createNew('My API Documentation');
  // proceed with merging documents, adding servers, etc., as shown in previous examples
  
  const expressServer = new smartexpress.Server({ cors: true });
  
  // Serve Swagger UI
  expressServer.addRoute('/api/documentation', new smartexpress.Handler('ALL', swaggerInstance.getSlashApiUiMiddleware()));

  // Optionally, serve documentation using ReDoc
  expressServer.addRoute('/api/redoc', new smartexpress.Handler('ALL', swaggerInstance.getSlashRedocMiddleware()));

  // Serve the raw Swagger JSON
  expressServer.addRoute('/api/swagger.json', new smartexpress.Handler('ALL', swaggerInstance.getSlashApiSchemaMiddleware()));
  
  // Start the server
  await expressServer.start(3000);
}
```

### Conclusion
`@push.rocks/smartswagger` offers a robust toolkit for working with Swagger documents in TypeScript, making it easier to build, merge, and serve comprehensive API documentation. Whether you're dealing with a single document or coordinating documentation across multiple services, `@push.rocks/smartswagger` provides the features necessary to streamline these processes.

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.