Run an API spec, no boilerplate needed #284

rafaelcaricio · 2016-09-12T22:07:41Z

Currently creating or developing an API with Connexion means that you need to Copy&Paste® a little boilerplate (small, but still) code.

import connexion

app = connexion.App(__name__, specification_dir='swagger/')
app.add_api('my_api.yaml')
app.run(port=8080)

Plus would be nice to configure some logging, more Copy&Paste®.

import logging
logging.basicConfig(level=logging.DEBUG)

Then would be nice to have a command line to run the project. Let me Copy&Paste® this little CLI tool boilerplate code structure.

import click
@click.command()
def run():
    ...

Alternatively, we could provide this minimal set of common practices of creating apps using Connexion bundled already within the installation of Connexion itself. To create a Microservice using Connexion, developers would only need to worry about the OpenAPI specification and the actual business logic/Python code. Then run the server using:

$ connexion run my_api.yaml

or

$ connexion run my_api.yaml -p 8080 --debug

Other use case is when during the development we want to run the server with partially implemented endpoints. Just run it:

$ connexion run my_unfinished_api.yaml --stub

Endpoints not implemented yet will return an error message saying that the operation is not yet implemented.

Those changes will make Connexion sail smoothly and providing fast satisfactory results will definitely improve the success of Connexion.

_Important to notice_
This is not a breaking change and all other functionality continues to work the same.

Changes proposed in this pull request:

Adds a the class StubResolver to provide a easy way to stub not implemented or not found operations;
Adds a command line tool for running specifications (connexion).

I hope you will like it! ❤️

coveralls · 2016-09-12T22:10:08Z

Coverage remained the same at 100.0% when pulling 82dcb61 on rafaelcaricio:cli into 1f317d2 on zalando:master.

coveralls · 2016-09-12T22:14:24Z

Coverage remained the same at 100.0% when pulling e7f96e4 on rafaelcaricio:cli into 1f317d2 on zalando:master.

coveralls · 2016-09-12T22:39:43Z

Coverage remained the same at 100.0% when pulling 97adb25 on rafaelcaricio:cli into 1f317d2 on zalando:master.

hjacobs · 2016-09-13T08:13:55Z

👍 for having connexion as a runnable console script --- but I would only keep one, i.e. remove the cnx alias.

NOTE: I haven't reviewed the whole PR yet...

jmcs · 2016-09-13T09:04:47Z

connexion/cli.py

+    sys.path.insert(1, path.abspath(base_path or '.'))
+
+    resolver = None
+    if stub:


As a future improvement we could implement a resolver that mocks a response based on the specification.

That is definitely interesting. There are some open source tools that do that, but bringing together the possibility to have partially mocked API's, that can morph in a fully implemented one, is a new approach.

What I'm looking to do is use my resolving swagger parser prance to generate test cases for an API. That's coming from realizing that swagger-tester isn't quite what I'd like it to be.

Some of that code might well be useful for generating the mocked response. One way or another it's going through the spec and generating stuff.

Just a thought. But I can't guarantee I'll be able to spend time on that.

jmcs · 2016-09-13T09:35:59Z

clickclick only supports python3, so we can't use it while we still support python 2.7.

rafaelcaricio · 2016-09-13T10:11:33Z

@jmcs That is 😒. I will try to make https://github.com/zalando/python-clickclick work with Python 2.7. Shouldn't be difficult.

rafaelcaricio · 2016-09-13T20:17:25Z

Clickclick supports Python 2.7 now in hjacobs/python-clickclick#9

coveralls · 2016-09-13T20:37:11Z

Coverage remained the same at 100.0% when pulling 8ef5794 on rafaelcaricio:cli into 58c99a0 on zalando:master.

coveralls · 2016-09-13T20:47:09Z

Coverage remained the same at 100.0% when pulling d9b59c6 on rafaelcaricio:cli into 58c99a0 on zalando:master.

coveralls · 2016-09-13T20:59:27Z

Coverage remained the same at 100.0% when pulling 7ecb585 on rafaelcaricio:cli into 58c99a0 on zalando:master.

coveralls · 2016-09-13T20:59:27Z

Coverage remained the same at 100.0% when pulling 7ecb585 on rafaelcaricio:cli into 58c99a0 on zalando:master.

hjacobs · 2016-09-13T21:46:06Z

requirements.txt

@@ -5,3 +5,4 @@ requests>=2.9.1
 six>=1.7
 strict-rfc3339>=0.6
 swagger_spec_validator>=2.0.2
+clickclick>=1.1


you can now require clickclick>=1.2 for Python 2.7 support

hjacobs · 2016-09-13T21:50:21Z

@rafaelcaricio we also need to add documentation for this CLI feature 😄

coveralls · 2016-09-14T04:57:58Z

Coverage remained the same at 100.0% when pulling 186f33b on rafaelcaricio:cli into 58c99a0 on zalando:master.

coveralls · 2016-09-14T22:56:37Z

Coverage remained the same at 100.0% when pulling 6076f96 on rafaelcaricio:cli into 58c99a0 on zalando:master.

jmcs · 2016-09-15T06:24:27Z

connexion/cli.py

+        resolver_error = 501
+
+    app = App(__name__,
+              swagger_json=hide_spec is False,


not hide_spec

jmcs · 2016-09-15T06:24:55Z

connexion/cli.py

+
+    app = App(__name__,
+              swagger_json=hide_spec is False,
+              swagger_ui=hide_console_ui is False,


not hide_console_ui

jmcs · 2016-09-15T07:56:52Z

👍

hjacobs · 2016-09-15T07:59:01Z

@rafaelcaricio how do you run the CLI from the workdir? Can we add a __main__.py file or at least add if __name__ == '__main__' into cli.py?

coveralls · 2016-09-15T08:00:01Z

Coverage remained the same at 100.0% when pulling 9b7cb99 on rafaelcaricio:cli into 58c99a0 on zalando:master.

rafaelcaricio · 2016-09-15T08:03:09Z

@hjacobs Added both.

coveralls · 2016-09-15T08:07:27Z

Coverage decreased (-0.3%) to 99.721% when pulling a2c074d on rafaelcaricio:cli into 58c99a0 on zalando:master.

rafaelcaricio · 2016-09-15T08:07:58Z

Coverage down... 😞

hjacobs · 2016-09-15T08:08:35Z

We should configure INFO logging by default to at least see the HTTP port...

hjacobs · 2016-09-15T08:11:21Z

connexion/cli.py

+
+    - BASE_MODULE_PATH (optional): filesystem path where the API endpoints handlers are going to be imported from.
+    """
+    logging_level = logging.ERROR


I would use INFO by default.

Or alternatively: ues WARN by default and make it more verbose with -v (INFO) and -vv (DEBUG).

I like the idea of changing levels by adding -v or -vv. Will do that.

hjacobs · 2016-09-15T08:14:09Z

Please use INFO log level by default, having no output at all is really confusing right now... (first I thought it hangs)

$ python3 -m connexion run examples/helloworld/swagger/helloworld-api.yaml  --stub

rafaelcaricio · 2016-09-15T08:26:32Z

@hjacobs I've added support for different log levels. Please check.

hjacobs · 2016-09-15T10:06:46Z

connexion/cli.py

+              is_flag=True, default=False)
+@click.option('--debug', '-d', help='Show debugging information.',
+              is_flag=True, default=False)
+@click.option('--verbose', '-v', help='Show logging information.',


nicer way of doing that: http://click.pocoo.org/5/options/#counting

coveralls · 2016-09-15T11:23:47Z

Coverage remained the same at 100.0% when pulling 2d23ac9 on rafaelcaricio:cli into 58c99a0 on zalando:master.

rafaelcaricio · 2016-09-15T11:32:21Z

@hjacobs done.

hjacobs · 2016-09-15T12:27:33Z

👍

hjacobs · 2016-09-15T12:47:42Z

Released in https://github.com/zalando/connexion/releases/tag/1.0.121

rafaelcaricio added 4 commits September 12, 2016 18:28

Provide CLI support for runnning specifications

c74d8cd

Run with specification stubs

e9d5a61

Refine stub option

9c5f6bc

Pass along all options available

82dcb61

jmcs added the in progress label Sep 12, 2016

Sort imports

e7f96e4

Sort imports

97adb25

jmcs reviewed Sep 13, 2016
View reviewed changes

rafaelcaricio mentioned this pull request Sep 13, 2016

Bad operationId to error status code #278

Merged

hjacobs mentioned this pull request Sep 13, 2016

Support Python 2.7 hjacobs/python-clickclick#8

Closed

Merge master into cli branch

8ef5794

Fix imports

d9b59c6

Fix imports

7ecb585

hjacobs reviewed Sep 13, 2016
View reviewed changes

rafaelcaricio added 2 commits September 14, 2016 06:54

Use clickclick>=1.2 with support to Python 2.7

186f33b

Remove cnx alias to CLI

dbe20e9

jmcs suggested changes Sep 15, 2016

View reviewed changes

Check that all options are passed correctly from the CLI module

9b7cb99

jmcs approved these changes Sep 15, 2016

View reviewed changes

Make connexion executable

a2c074d

Very simple code to run module, no tests :(

b3fc3ff

hjacobs suggested changes Sep 15, 2016

View reviewed changes

No coverage for those two lines

b57ebfa

rafaelcaricio added 2 commits September 15, 2016 10:16

Use INFO log level by default

46fa019

Support different log levels in CLI

c1d55c1

rafaelcaricio added 2 commits September 15, 2016 10:29

Make sure very verbose is the same as debug

d71674b

Fix flake8 checks

08b20e5

hjacobs reviewed Sep 15, 2016

View reviewed changes

Nicer verbosity impl.

2d23ac9

hjacobs approved these changes Sep 15, 2016

View reviewed changes

hjacobs merged commit 8b978f4 into spec-first:master Sep 15, 2016

jmcs removed the in progress label Sep 15, 2016

Run an API spec, no boilerplate needed #284

Run an API spec, no boilerplate needed #284

Conversation

rafaelcaricio commented Sep 12, 2016 • edited

coveralls commented Sep 12, 2016

coveralls commented Sep 12, 2016

coveralls commented Sep 12, 2016 • edited

hjacobs commented Sep 13, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jmcs commented Sep 13, 2016

rafaelcaricio commented Sep 13, 2016

rafaelcaricio commented Sep 13, 2016

coveralls commented Sep 13, 2016

coveralls commented Sep 13, 2016

coveralls commented Sep 13, 2016

coveralls commented Sep 13, 2016

Choose a reason for hiding this comment

hjacobs commented Sep 13, 2016

coveralls commented Sep 14, 2016

coveralls commented Sep 14, 2016 • edited

Choose a reason for hiding this comment

jmcs Sep 15, 2016 • edited

Choose a reason for hiding this comment

jmcs commented Sep 15, 2016

hjacobs commented Sep 15, 2016

coveralls commented Sep 15, 2016 • edited

rafaelcaricio commented Sep 15, 2016

coveralls commented Sep 15, 2016 • edited

rafaelcaricio commented Sep 15, 2016

hjacobs commented Sep 15, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hjacobs commented Sep 15, 2016

rafaelcaricio commented Sep 15, 2016

Choose a reason for hiding this comment

coveralls commented Sep 15, 2016 • edited

rafaelcaricio commented Sep 15, 2016

hjacobs commented Sep 15, 2016

hjacobs commented Sep 15, 2016

rafaelcaricio commented Sep 12, 2016 •

edited

coveralls commented Sep 12, 2016 •

edited

coveralls commented Sep 14, 2016 •

edited

jmcs Sep 15, 2016 •

edited

coveralls commented Sep 15, 2016 •

edited

coveralls commented Sep 15, 2016 •

edited

coveralls commented Sep 15, 2016 •

edited