Peeman


NamePeeman JSON
Version 1.0.4 PyPI version JSON
download
home_page
SummaryA Postman to OpenAPI spec converter with mocking facilities
upload_time2021-01-07 10:58:09
maintainer
docs_urlNone
author
requires_python>=3.5
licenseMIT
keywords api openapi rest specification oas documentation
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Peeman

A postman to openapi spec conversion tool, which automatically

- Converts your postman collection (2.1) to OpeanAPI Spec (3.0.0)
- Mocks your openapi collection to generate responses from postman examples

Other than these, this tool can easily handle ignored fields in responses (explained below)

**NOTE** Please use postman collection ver 2.1 export (and not 2.0 or earlier). This library only support postman collection 2.1

## Installation

**NOTE** This repo needs you to have python 3.5+ installed

As of now, I haven't pushed this tool to pipy repo yet. Hence, its clone only for now.

### PIP

```sh
pip install peeman
```


## Quick Start

This tool can be used as a python package or as a standalone cli.

To start, simply type `peeman --help` and it will display help

```sh
Usage: openman [OPTIONS] COMMAND [ARGS]...

  Convert or mock your postman collection to openapi schema

Options:
  --help  Show this message and exit.

Commands:
  convert
  mock
```

### Convert postman to openapi spec

Easy!! Just use `convert` command (default output is yaml)

```sh
peeman convert postman-collection.json spec.yaml
```

Or, you can output to json by

```sh
peeman convert -f json postman-collection.json spec.yaml
```

### Mocking spec

I am using the some cherry on top of the awesome project [Connexion](https://github.com/zalando/connexion)

Basically, I am using postman example as mock responses, given the request has matching parameters (query, headers etc.). Even if they do not match, this tool gives out the mock responses for provided schema.

```sh
peeman mock spec.yaml
```

### Ignore schema

Sometimes, your api responses have some data which varies. For instance, consider this response for the api `POST /user`:

```json
{
    "result": {
        "timestamp": 1572696732,
        "username": "abc",
        "tags": {
            "tag1" : "something",
            "tag3": "somethig else"
        },
        "some-changing-key": "whatever"
    }
}
```

You do want to record the `username`, `timestamp` fields, but what about `some-changing-key` field? What about fields inside `tags`? You want to keep the `tags` key as it will always be included in response, but do not want to keep `some-changing-key` as it may or maynot appear in responses.

**Sometimes you may want to ignore only the values of a key, while sometimes you want the key value pair to be ignored alltogether**

For such cases, you may not want to document them. For such purpose, **Ignore file** is used.

In ignore file, you can document the fields you want the openman to ignore. It uses the [jsonpath-rw](https://pypi.org/project/jsonpath-rw/) library and uses its syntax (which is quite easy to learn).

**To ignore only values but keep the keys**, simple use the `jsonpath-rw` syntax that points to the key. For ex- `$.result.tags.[*]` will find everything inside `tags` field in `result` object.

**To ignore both key and values**, simply use the above method, i.e. write your `jsonpath-rw` regex that matches the path, and *append* `:a` to it. For example, if you want to delete everything inside tag *including* tag field itself, you can do so by: `$.result.tags.[*]:a`


Taking above example, you want to ignore following fields:

- everything inside `tags` (ignore value but NOT the key `tags`)
- `some-changing-key` field (ignore both key and value)

You can define them in a file `ignore.yaml` as such:

```yaml
schema:
   /user:
     post:
       200:
         - '$.result.tags.[*]' //Ignore everything inside tags field
         - '$.result.some-changing-key:a' //Ignore 'some-changing-key'. Note the leading :a 
```

and then you can convert your postman collection to openapi spec without these fields:

```sh
peeman -i ignore.yaml postman-collection.json spec.yaml
```

PS: Leading `:a` in jsonpath-rw syntax with ignore both the key and values, otherwise only values are ignored.

## Change spec format

The default output conversion format is `yaml`. However, you can easily change the format to json by:

```sh
peeman -f json postman-collection.json spec.json
```



            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "Peeman",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.5",
    "maintainer_email": "",
    "keywords": "api,openapi,rest,specification,oas,documentation",
    "author": "",
    "author_email": "",
    "download_url": "https://files.pythonhosted.org/packages/74/f4/463aeb09a718d74aa23a61d6b9b5de73987390211d63a219929138e1a60e/Peeman-1.0.4.tar.gz",
    "platform": "",
    "description": "# Peeman\n\nA postman to openapi spec conversion tool, which automatically\n\n- Converts your postman collection (2.1) to OpeanAPI Spec (3.0.0)\n- Mocks your openapi collection to generate responses from postman examples\n\nOther than these, this tool can easily handle ignored fields in responses (explained below)\n\n**NOTE** Please use postman collection ver 2.1 export (and not 2.0 or earlier). This library only support postman collection 2.1\n\n## Installation\n\n**NOTE** This repo needs you to have python 3.5+ installed\n\nAs of now, I haven't pushed this tool to pipy repo yet. Hence, its clone only for now.\n\n### PIP\n\n```sh\npip install peeman\n```\n\n\n## Quick Start\n\nThis tool can be used as a python package or as a standalone cli.\n\nTo start, simply type `peeman --help` and it will display help\n\n```sh\nUsage: openman [OPTIONS] COMMAND [ARGS]...\n\n  Convert or mock your postman collection to openapi schema\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  convert\n  mock\n```\n\n### Convert postman to openapi spec\n\nEasy!! Just use `convert` command (default output is yaml)\n\n```sh\npeeman convert postman-collection.json spec.yaml\n```\n\nOr, you can output to json by\n\n```sh\npeeman convert -f json postman-collection.json spec.yaml\n```\n\n### Mocking spec\n\nI am using the some cherry on top of the awesome project [Connexion](https://github.com/zalando/connexion)\n\nBasically, I am using postman example as mock responses, given the request has matching parameters (query, headers etc.). Even if they do not match, this tool gives out the mock responses for provided schema.\n\n```sh\npeeman mock spec.yaml\n```\n\n### Ignore schema\n\nSometimes, your api responses have some data which varies. For instance, consider this response for the api `POST /user`:\n\n```json\n{\n    \"result\": {\n        \"timestamp\": 1572696732,\n        \"username\": \"abc\",\n        \"tags\": {\n            \"tag1\" : \"something\",\n            \"tag3\": \"somethig else\"\n        },\n        \"some-changing-key\": \"whatever\"\n    }\n}\n```\n\nYou do want to record the `username`, `timestamp` fields, but what about `some-changing-key` field? What about fields inside `tags`? You want to keep the `tags` key as it will always be included in response, but do not want to keep `some-changing-key` as it may or maynot appear in responses.\n\n**Sometimes you may want to ignore only the values of a key, while sometimes you want the key value pair to be ignored alltogether**\n\nFor such cases, you may not want to document them. For such purpose, **Ignore file** is used.\n\nIn ignore file, you can document the fields you want the openman to ignore. It uses the [jsonpath-rw](https://pypi.org/project/jsonpath-rw/) library and uses its syntax (which is quite easy to learn).\n\n**To ignore only values but keep the keys**, simple use the `jsonpath-rw` syntax that points to the key. For ex- `$.result.tags.[*]` will find everything inside `tags` field in `result` object.\n\n**To ignore both key and values**, simply use the above method, i.e. write your `jsonpath-rw` regex that matches the path, and *append* `:a` to it. For example, if you want to delete everything inside tag *including* tag field itself, you can do so by: `$.result.tags.[*]:a`\n\n\nTaking above example, you want to ignore following fields:\n\n- everything inside `tags` (ignore value but NOT the key `tags`)\n- `some-changing-key` field (ignore both key and value)\n\nYou can define them in a file `ignore.yaml` as such:\n\n```yaml\nschema:\n   /user:\n     post:\n       200:\n         - '$.result.tags.[*]' //Ignore everything inside tags field\n         - '$.result.some-changing-key:a' //Ignore 'some-changing-key'. Note the leading :a \n```\n\nand then you can convert your postman collection to openapi spec without these fields:\n\n```sh\npeeman -i ignore.yaml postman-collection.json spec.yaml\n```\n\nPS: Leading `:a` in jsonpath-rw syntax with ignore both the key and values, otherwise only values are ignored.\n\n## Change spec format\n\nThe default output conversion format is `yaml`. However, you can easily change the format to json by:\n\n```sh\npeeman -f json postman-collection.json spec.json\n```\n\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A Postman to OpenAPI spec converter with mocking facilities",
    "version": "1.0.4",
    "split_keywords": [
        "api",
        "openapi",
        "rest",
        "specification",
        "oas",
        "documentation"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "55114d95c9e3c70ab9ef9b15ba2b75ef",
                "sha256": "6ae299b72d6a8ad5ec10b23c8f781ab5203f01f1251242a548dcf14cab15acdd"
            },
            "downloads": -1,
            "filename": "Peeman-1.0.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "55114d95c9e3c70ab9ef9b15ba2b75ef",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.5",
            "size": 19737,
            "upload_time": "2021-01-07T10:58:07",
            "upload_time_iso_8601": "2021-01-07T10:58:07.764584Z",
            "url": "https://files.pythonhosted.org/packages/78/2b/4532deafa7bc2a74fc4d1b76b4ed0d28e246de6a6ce2fb84d043ab35fe6b/Peeman-1.0.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "399f1b8d0223c3554bf47623c313ea6e",
                "sha256": "7481a2de882f0d36c58d0d3a2cceb3b4fb90e8ff6d8de88e764638fba8b54708"
            },
            "downloads": -1,
            "filename": "Peeman-1.0.4.tar.gz",
            "has_sig": false,
            "md5_digest": "399f1b8d0223c3554bf47623c313ea6e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.5",
            "size": 15231,
            "upload_time": "2021-01-07T10:58:09",
            "upload_time_iso_8601": "2021-01-07T10:58:09.387321Z",
            "url": "https://files.pythonhosted.org/packages/74/f4/463aeb09a718d74aa23a61d6b9b5de73987390211d63a219929138e1a60e/Peeman-1.0.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-01-07 10:58:09",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "peeman"
}
        
Elapsed time: 0.23264s