Kong / Kong/insomnia

[FEATURE REQUEST] Convert request description from OpenAPI schema into Insomnia's request documentation

Open
#3,911 4 comments 0 reactions 0 assignees View on GitHub
C-improvement PA-openapi-2-kong S-verified
Dominant language
TypeScript
Stars
40k
Forks
2.4k
Avg merge
2d 13h
Merged PRs (30d)
61

Description

Problem occurs when importing data from an **openapi.json** file.
Paths may have a "description" property:
image

There is a description property in insomnia requests (for the documentation):
image

**Problem**
Insomnia's import feature doesn't use requests' description from the openapi schema.

Consequently, the documentations that I am writing in the source code aren't available in the documentation tab of insomnia's requests, which is a real downer.

**Reproduce**
Import this openapi schema:
```json
{"openapi": "3.0.2", "info": {"title": "Really light API", "version": "0.1.0"}, "paths": {"/": {"get": {"summary": "Name Of The Request Handler", "description": "Some description here", "operationId": "name_of_the_request_handler__get", "responses": {"200": {"description": "Successful Response", "content": {"application/json": {"schema": {}}}}}}}}}
```

**Desktop:**
- OS: macOS 10.15.7
- Installation Method: `.dmg`file from https://insomnia.rest/download

**C/C from the "About Insomnia" window**
- Version: Insomnia 2021.4.1
- Release date: 7/7/2021
- OS: Darwin x64 19.6.0
- Electron: 9.3.5
- Node: 12.14.1
- V8: 8.3.110.13-electron.0
- Architecture: x64
- node-libcurl: libcurl/7.73.0 OpenSSL/1.1.1k zlib/1.2.11 brotli/1.0.9 zstd/1.4.9 libidn2/2.1.1 libssh2/1.9.0 nghttp2/1.42.0

Contributor guide

Open the contributing guide

Research direction

Use the supplied openapi.json reproduction and start at Insomnia's OpenAPI import feature. Trace how the operation description is mapped into an imported request, then verify that "Some description here" appears in the request's documentation tab. The work is done when imported OpenAPI operation descriptions are preserved in request documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.