# insomswagger > A command-line tool for converting JSON exported by Insomnia to Swagger format, as well as converting a swagger-formatted json file into a swagger-formatted annotation to facilitate documentation generation. Latest version **1.5.0** (published 2024-02-19) · SEE LICENSE IN License.md license · 0 weekly downloads > **Deprecated.** This package is deprecated. ## Install ```sh npm install insomswagger pnpm add insomswagger yarn add insomswagger bun add insomswagger ``` Provides the command `insomswagger`. ## Health **Score 10/100 (F)** — status: deprecated. Negative: deprecated. ## Facts | | | |---|---| | Version | 1.5.0 | | Published | 2024-02-19 | | First published | 2023-12-26 | | Weekly downloads | 0 | | License | SEE LICENSE IN License.md | | TypeScript types | none | | Module format | CommonJS | | Node | >=18 | | Dependencies | 2 | | Unpacked size | 1.8 MB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 3 | | Author | Magid Ba | | Maintainers | magid_ba | | Keywords | insomnia, swagger, docs, documentation, insomswagger | ## Links - npm: https://www.npmjs.com/package/insomswagger - Repository: https://github.com/bamagid/insom-swagger - Homepage: https://github.com/bamagid/insom-swagger#readme - Issues: https://github.com/bamagid/insom-swagger/issues - npm.io page: https://npm.io/package/insomswagger ## Dependencies (2) - [open](https://npm.io/package/open.md) 10.0.3 - [js-yaml](https://npm.io/package/js-yaml.md) ^4.1.0 ## Alternatives - [@cantoo/pdf-lib](https://npm.io/package/@cantoo/pdf-lib.md) — 297.9K weekly downloads - [datatables.net-buttons](https://npm.io/package/datatables.net-buttons.md) — 200.1K weekly downloads - [@ckeditor/ckeditor5-export-pdf](https://npm.io/package/@ckeditor/ckeditor5-export-pdf.md) — 167.0K weekly downloads - [scanbot-web-sdk](https://npm.io/package/scanbot-web-sdk.md) — 15.0K weekly downloads - [@syncfusion/ej2-angular-pdfviewer](https://npm.io/package/@syncfusion/ej2-angular-pdfviewer.md) — 8.8K weekly downloads ## Recent versions - 1.5.0 (latest) — 2024-02-19 - 1.4.3 — 2024-01-29 - 1.4.2 — 2024-01-29 - 1.4.1 — 2024-01-26 - 1.4.0 — 2024-01-26 - 1.3.8 — 2024-01-18 - 1.3.7 — 2024-01-18 - 1.3.6 — 2024-01-18 - 1.3.5 — 2024-01-18 - 1.3.4 — 2024-01-18 - 1.3.3 — 2024-01-18 - 1.3.2 — 2024-01-18 - 1.3.1 — 2024-01-18 - 1.3.0 — 2024-01-18 - 1.2.2 — 2023-12-28 - … 14 more at https://npm.io/package/insomswagger/versions ## README # Insomswagger ## Introduction Insomswagger is a versatile Node.js package designed to simplify the process of converting exported JSON from Insomnia into Swagger documentation. This utility offers flexibility by allowing users to generate either Swagger JSON files or PHP annotations based on their specific needs. Whether you prefer a clean Swagger JSON representation or you're working within a PHP environment using annotations, this package has you covered. Easily create clear and concise API documentation tailored to your project requirements. ## Installation Before using the package, ensure you have Node.js installed on your machine. If not, you can download it [here](https://nodejs.org/). ## Usage To utilize the package, follow these steps: 1. Install the package globally: ```bash npm install -g insomswagger ``` 2. Navigate to the directory containing your input file. 3. Run the following command: - For Swagger PHP Annotations: ```bash insomswagger -a [inputFilePath] [outputFilePath] ``` - For Swagger JSON: ```bash insomswagger -j [inputFilePath] [outputFilePath] ``` - For Swagger Yaml: ```bash insomswagger -y [inputFilePath] [outputFilePath] ``` If `outputFilePath` is not provided, the default names (`annotations.php` for -a ,api-docs.yaml for -y and `api-docs.json` for -j) will be used. - To Update an Existing Installation: ```bash insomswagger update ``` This command will update this package to the latest version. ## Tips for Organizing Files in Insomnia For optimal results when generating annotations, consider organizing your files in Insomnia: - Group requests under folders based on their functionality. - Use meaningful names for requests and folders. - Provide descriptions for requests and folders. ## Adding Annotations to Controllers To incorporate the generated annotations into your controllers, follow these steps: 1. Open the file containing the generated annotations in your preferred IDE. 2. Copy the annotations corresponding to each controller and method. 3. Paste the annotations into the respective controller and method in your codebase. Annotations with the same tags are placed side by side if you've organized your Insomnia JSON accordingly. # Viewing Swagger Documentation To view the Swagger documentation in your Laravel project, you can use tools like [Darkaonline/L5-Swagger](https://github.com/DarkaOnLine/L5-Swagger). 1. If your Laravel project is not using L5-Swagger yet, you have two options: a. Follow the manual installation instructions in the [L5-Swagger repository](https://github.com/DarkaOnLine/L5-Swagger). b. Alternatively, you can run the following command, which automates the installation of Swagger documentation for your Laravel project using [Darkaonline/L5-Swagger](https://github.com/DarkaOnLine/L5-Swagger): ```bash insomswagger install ``` 2. Once L5-Swagger has been installed, it generates an api-docs folder in the `storage` directory. If this has not yet been generated, create it. 3.copy the `api-docs.json` file generated by the command `bash insomswagger -j [inputFilePath] [outputFilePath] ` and paste it in `storage/api-docs/api-docs.json` . NB: If you are told that a file with the same name exists, choose the "replace" option. Now, when you access the Swagger documentation in your Laravel project, it will reflect the API documentation generated from your Insomnia collection. ## Testing with Images and Multipart Support Insomswagger allows you to test your API endpoints with various data types, including images and multipart requests. ### Uploading Images When testing your API, you can easily upload images by using the `multipart/form-data` content type. In your Insomnia collection, create a request with the `POST` method and set the request body type to `multipart/form-data`. Add a field with the type `file` to upload an image. ### Multipart Requests Insomswagger supports multipart requests, allowing you to send multiple types of data in a single request. To test with multipart data, configure your request in Insomnia with the appropriate content type (`multipart/form-data`). Include the necessary fields, such as text and file inputs. ## Path Parameters When testing your API endpoints in Insomnia, make sure to provide values for path parameters. In your API routes, path parameters are represented within curly braces `{}`. In Insomnia, navigate to the query parameters section and add a parameter with the same name as the one in your route, enclosed in curly braces. For example, if your route is `/api/users/{userId}`, add a query parameter named `userId` with the desired value. This ensures accurate testing of your API, considering the dynamic nature of path parameters. ## Examples Here are a few examples of how to use the package: - For Swagger PHP Annotations: ```bash insomswagger -a insomnia-export.json my-annotations.php ``` - For Swagger JSON: ```bash insomswagger -j insomnia-export.json my-api-docs.json ``` - For Swagger Yaml: ```bash insomswagger -y insomnia-export.json my-api-docs.json ``` - For Darkaonline/l5-swagger installation: ```bash insomswagger install ``` ## License This package is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details. ## Author Magid Ba ## Issues and Contributions If you encounter any issues or want to contribute to the project, please visit the [GitHub repository](https://github.com/bamagid/insomnia-docs-swagger). Happy documenting! ``` ``` --- _Source: https://npm.io/package/insomswagger · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._