update tsconfig
This commit is contained in:
parent
10ef8aac8f
commit
cae7749d9d
@ -8,14 +8,24 @@
|
||||
"shortDescription": "a swagger tookit for working with swagger files",
|
||||
"npmPackagename": "@push.rocks/smartswagger",
|
||||
"license": "MIT",
|
||||
"projectDomain": "push.rocks"
|
||||
"projectDomain": "push.rocks",
|
||||
"description": "A Swagger toolkit for working with Swagger files, including merging documents and serving APIs with UI.",
|
||||
"keywords": [
|
||||
"swagger",
|
||||
"API documentation",
|
||||
"swagger-ui",
|
||||
"redoc",
|
||||
"express middleware",
|
||||
"typescript",
|
||||
"openapi"
|
||||
]
|
||||
}
|
||||
},
|
||||
"npmci": {
|
||||
"npmGlobalTools": [],
|
||||
"npmAccessLevel": "public"
|
||||
},
|
||||
"tsdocs": {
|
||||
"tsdoc": {
|
||||
"legal": "\n## License and Legal Information\n\nThis 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. \n\n**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.\n\n### Trademarks\n\nThis 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.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n"
|
||||
}
|
||||
}
|
||||
11
package.json
11
package.json
@ -2,7 +2,7 @@
|
||||
"name": "@push.rocks/smartswagger",
|
||||
"version": "1.1.3",
|
||||
"private": false,
|
||||
"description": "a swagger tookit for working with swagger files",
|
||||
"description": "A Swagger toolkit for working with Swagger files, including merging documents and serving APIs with UI.",
|
||||
"main": "dist_ts/index.js",
|
||||
"typings": "dist_ts/index.d.ts",
|
||||
"author": "Lossless GmbH",
|
||||
@ -44,5 +44,14 @@
|
||||
"cli.js",
|
||||
"npmextra.json",
|
||||
"readme.md"
|
||||
],
|
||||
"keywords": [
|
||||
"swagger",
|
||||
"API documentation",
|
||||
"swagger-ui",
|
||||
"redoc",
|
||||
"express middleware",
|
||||
"typescript",
|
||||
"openapi"
|
||||
]
|
||||
}
|
||||
1
readme.hints.md
Normal file
1
readme.hints.md
Normal file
@ -0,0 +1 @@
|
||||
|
||||
163
readme.md
163
readme.md
@ -1,39 +1,144 @@
|
||||
# @pushrocks/smartswagger
|
||||
# @push.rocks/smartswagger
|
||||
a swagger tookit for working with swagger files
|
||||
|
||||
## Availabililty and Links
|
||||
* [npmjs.org (npm package)](https://www.npmjs.com/package/@pushrocks/smartswagger)
|
||||
* [gitlab.com (source)](https://gitlab.com/pushrocks/smartswagger)
|
||||
* [github.com (source mirror)](https://github.com/pushrocks/smartswagger)
|
||||
* [docs (typedoc)](https://pushrocks.gitlab.io/smartswagger/)
|
||||
|
||||
## Status for master
|
||||
|
||||
Status Category | Status Badge
|
||||
-- | --
|
||||
GitLab Pipelines | [](https://lossless.cloud)
|
||||
GitLab Pipline Test Coverage | [](https://lossless.cloud)
|
||||
npm | [](https://lossless.cloud)
|
||||
Snyk | [](https://lossless.cloud)
|
||||
TypeScript Support | [](https://lossless.cloud)
|
||||
node Support | [](https://nodejs.org/dist/latest-v10.x/docs/api/)
|
||||
Code Style | [](https://lossless.cloud)
|
||||
PackagePhobia (total standalone install weight) | [](https://lossless.cloud)
|
||||
PackagePhobia (package size on registry) | [](https://lossless.cloud)
|
||||
BundlePhobia (total size when bundled) | [](https://lossless.cloud)
|
||||
Platform support | [](https://lossless.cloud) [](https://lossless.cloud)
|
||||
## 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.
|
||||
|
||||
Use TypeScript for best in class intellisense
|
||||
### 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.
|
||||
|
||||
## Contribution
|
||||
#### From an External Swagger File URL
|
||||
```typescript
|
||||
import { Smartswagger } from '@push.rocks/smartswagger';
|
||||
|
||||
We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
For further information read the linked docs at the top of this readme.
|
||||
#### Creating a New Swagger Document
|
||||
```typescript
|
||||
import { Smartswagger } from '@push.rocks/smartswagger';
|
||||
|
||||
> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh)
|
||||
| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
|
||||
async function createNewSwaggerDoc() {
|
||||
const swaggerInstance = await Smartswagger.createNew('My API Documentation');
|
||||
// Now you have a new Smartswagger instance with basic setup
|
||||
}
|
||||
```
|
||||
|
||||
[](https://maintainedby.lossless.com)
|
||||
### 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user