Giter Club home page Giter Club logo

openapi-cli-tool's Introduction

openapi-cli-tool

Build Status

openapi-cli-tool

OpenAPI (Swagger 3.x) CLI Tool.

  • Supports multiple file extensions (json|yaml|yml).
  • Can list up defined API paths.
  • Display an API specification which is resolved ($ref).
  • Bundle multi-file into one (output to json|yaml|html).
  • OAS interactive scaffolding.

Requirements

Python 2.7, 3.4 <=.

Installation

With pip:

$ pip install openapi-cli-tool

Manually:
Clone the repository and execute the Python installation command on your machine.

$ pip -r requirements.txt install
$ python setup.py install

Then openapi-cli-tool command is installed.

Usage

$ openapi-cli-tool --help
Usage: openapi-cli-tool [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  bundle    Bundle multiple files into one.
  list      List up API paths in a file or directory.
  resolve   Display `$ref` resolved API specification.
  scaffold  Interactively create a simple OpenAPI Specification.

Bundle

Bundle multi-file specifications into one, regardless of file extension (json|yaml|yml).

$ openapi-cli-tool bundle --help
Usage: openapi-cli-tool bundle [OPTIONS] FILE_PATHS

  Bundle multiple files into one.

Options:
  -f, --file TEXT  Load common objects such as info and servers from a
                   specific file. Default is a file which is the top of list
                   command result.
  -t, --type TEXT  Export data type. {json|yaml|html}  [default: json]
  --help           Show this message and exit.

example:

$ openapi-cli-tool bundle -t html file1.json file2.yaml` > ./specification.html

In the html file, an unpkg version of swagger-ui is embedded. Rendered screenshot below:

bundle-html-img

List

List up API paths from a file/directory regardless of the file extension (json|yaml|yml).

$ openapi-cli-tool list `find ./spec`

Method    Path       File
--------  ---------  ------------------------------------------
PUT       /avatar    ./tests/resources/spec/sample.yml
GET       /follwers  ./tests/resources/spec/folder1/sample2.yaml
POST      /follwers  ./tests/resources/spec/folder1/sample2.yaml
PUT       /follwers  ./tests/resources/spec/folder1/sample2.yaml
POST      /pets      ./tests/resources/spec/sample.yml
GET       /posts     ./tests/resources/spec/folder1/sample.json
POST      /posts     ./tests/resources/spec/folder1/sample.json
GET       /users     ./tests/resources/spec/folder1/sample.json
POST      /users     ./tests/resources/spec/folder1/sample.json

Resolve

Display an API specification which is resolved from a multi-file API specification via $ref pointers.

Usage: openapi-cli-tool resolve [OPTIONS] METHOD PATH FILE_PATHS

  Display `$ref` resolved API specification.

Options:
  -t, --type TEXT  Export data type. {json|yaml}  [default: json]
  --help           Show this message and exit.

example:

$ openapi-cli-tool resolve post /cats `find ./tests/resources/spec`

Scaffold

Interactively input information of your API.
A simple OpenAPI Specification is generated from your prompt.

$ openapi-cli-tool scaffold

Please enter title [""]: sample
Please enter version [v1.0]:
Please enter license [Apache 2.0]:
Please enter server url [http://example.com]:
Please enter path [/]: /example
Please enter method for /example [get|post|put|delete|head|option|trace]: get
Please enter description for get /example [""]: sample get endpoint
Please enter response code for get /example [200]:

openapi-cli-tool's People

Contributors

hakopako avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

openapi-cli-tool's Issues

how can I add parent url in list method of the tool

Hi,

Would be really useful to have a additional trigger so we can add a extra column for the "parent url" path in list like from the below:

Method      Path                                              File
----------  ------------------------------------------------  ------------------------
GET          /app_packages                                     MEC010-2_AppPkgMgmt.yaml
POST        /app_packages                                     MEC010-2_AppPkgMgmt.yaml

to

Method      Path                                              File
----------  ------------------------------------------------  ------------------------
GET         app-pkgm/v1/app_packages                                     MEC010-2_AppPkgMgmt.yaml
POST       app-pkgm/v1/app_packages                                     MEC010-2_AppPkgMgmt.yaml

from the OpenApi yaml you can find it under:

servers:
  - url: 'https://localhost/app_lcm/v1'
openapi: 3.0.0
tags:
  - name: app-lcm

Yeah I know its not that difficult to change the code and add it, will try to experiment!!
Maybe some changes in utils/repository.py
Thanks for the tool!!!

Unable to resolve local file $ref

Description

Hi, I'm unable to resolve file paths from $ref that includes local file. This is also the case with list and bundle.

Expected behavior

Not sure, since I don't have an example output. I expect some kind of list of the methods for the given $ref.

Current behavior

[]

Steps to reproduce

  1. mkdir example && cd example
  2. touch index.yaml
  3. mkdir -p pet
  4. touch pet/pet.yaml
  5. Populate index.yaml
cat << EOF > index.yaml
openapi: 3.0.1
info:
  title: Swagger Petstore
  description: 'This is a sample server Petstore server.  You can find out more about     Swagger
    at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For
    this sample, you can use the api key `special-key` to test the authorization     filters.'
  termsOfService: http://swagger.io/terms/
  contact:
    email: [email protected]
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
- url: https://petstore.swagger.io/v2
- url: http://petstore.swagger.io/v2
tags:
- name: pet
  description: Everything about your Pets
  externalDocs:
    description: Find out more
    url: http://swagger.io
- name: store
  description: Access to Petstore orders
- name: user
  description: Operations about user
  externalDocs:
    description: Find out more about our store
    url: http://swagger.io
paths:
  /pet:
    $ref: './pet/pet.yaml'
EOF
  1. Populate pet/pet.yaml
cat << EOF > pet/pet.yaml
put:
  tags:
  - pet
  summary: Update an existing pet
  operationId: updatePet
  requestBody:
    description: Pet object that needs to be added to the store
    required: true
  responses:
    400:
      description: Invalid ID supplied
      content: {}
    404:
      description: Pet not found
      content: {}
    405:
      description: Validation exception
      content: {}
  security:
  - petstore_auth:
    - write:pets
    - read:pets
  x-codegen-request-body-name: body
post:
  tags:
  - pet
  summary: Add a new pet to the store
  operationId: addPet
  requestBody:
    description: Pet object that needs to be added to the store
    required: true
  responses:
    405:
      description: Invalid input
      content: {}
  security:
  - petstore_auth:
    - write:pets
    - read:pets
  x-codegen-request-body-name: body
EOF
  1. Resolve from the root of the example dir: openapi-cli-tool resolve -t yaml put '/pet' index.yaml

Environment

  • Ubuntu 16.04
  • pipenv, version 2018.11.26
  • Python 3.6

s it possible to separate paths into separate files?

openapi: 3.0.0
info:
  title: XXXXXXX
  version: '0.0.1'
  license:
    name: MIT
  x-complex-type:
    supported:
      - version: '2.0'
        level: baseapi
servers:
  - url: https://{environment}.demo.com
    description: Select a server
    variables:
      environment:
        enum:
          - api
          - api.dev
          - api.test
        default: api
paths:
  $ref: './groups/statusGroup.yaml'

file statusGroups.yaml

/status:
  get:
    $ref: '../endpoint/status/getVersion.yaml'

There comes a time when the swagger.yaml file has many paths and reading them is difficult. Is it possible to separate the groups/tags into separate files? I'm trying to create one file per endpoint group for easy reading but the paths: property doesn't accept $ref: in its schema. It would be great to be able to do this.

image

image

maximum recursion issue

With one of my swagger files I am getting an issue here:

Failed to load reference. file=swagger-....json $ref=#/definitions/ClusterCrudResponse (maximum recursion depth exceeded in cmp)

I found out I can increase the recursionlimit which I did:
https://docs.python.org/2/library/sys.html#sys.setrecursionlimit
sys.setrecursionlimit(20000)
I checked with jq and found about 13000 keys in the file I have.

But when I increased the value it needs some time and then python crashes with a segmentation fault error: EXC_BAD_ACCESS (SIGSEGV).

I found here a blog post that there are solutions for getting out of that situation but I don't know how to adapt it to this python program here.
http://neopythonic.blogspot.com/2009/04/tail-recursion-elimination.html

Could you please have a look?
Thank you.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.