Added Swagger generation #569

elasti-ron · 2017-11-07T12:12:38Z

Hi,

I've added the capability to auto-generate static Swagger definition files from the Apipie DSL.

The resulting Swagger (OpenAPI 2.0) compliant JSON file can then be used to auto-generate REST clients, imported into tools like Postman, and so forth.

Swagger generation is implemented by crawling through Apipie's resource_descriptions construct.

The DSL is slightly enhanced to allow indication of default values of optional parameters.

There are a few configuration options that can be used to change the overall structure of the generated swagger file, in order to support both in:formData and in:body REST request styles.

Looking forward to hear your thoughts.

iNecas · 2017-11-08T17:30:10Z

lib/apipie/swagger_generator.rb

@@ -0,0 +1,583 @@
+module Apipie
+  module Validator
+    class EnumValidator < BaseValidator


Why not putting it directly to the validator definition?

iNecas · 2017-11-08T17:34:13Z

lib/apipie/swagger_generator.rb

+    end
+
+
+    def save_and_compare


This method is not being called from any place? Should it be exposed from the rake?

iNecas · 2017-11-08T17:37:41Z

lib/apipie/swagger_generator.rb

+    # note that at the moment, this only takes operation ids into account, and ignores parameter
+    # definitions, so it's only partially useful.
+    def include_op_id_in_master_identifier(op_id)
+      @master_id = Zlib::crc32("#{@master_id} #{op_id}")


we should probably require zlib somewhere: it's probably loaded by rails somewhere, but just to be on safe side

iNecas · 2017-11-08T17:38:59Z

lib/apipie/swagger_generator.rb

+      # print "??? RESEARCH: [#{ruby_name_for_method(@current_method)}] -- #{msg}\n"
+    end
+
+    def dump_param_desc(param_desc)


Unused method?

iNecas · 2017-11-08T17:42:37Z

There are some unused methods and commented code, that should be cleaned first. I have not tested this yet, but my view on this is we could get this in pretty soon, as it has not influence on other features, and can be pretty useful for many folks.

iNecas · 2017-11-08T17:44:57Z

I wonder if we could have a test on checking that the swagger output valid, in the tests.

iNecas · 2017-11-08T17:46:17Z

Another question: would it make sense to expose this via an /apidoc endpoint, similarly as we have with apidoc.json?

elasti-ron · 2017-11-09T12:57:00Z

Thanks @iNecas - good points. I'll push a cleaned-up version early next week.

Re exposing via /apidoc: yes, would be useful. Would probably make sense to auto-fill the swagger host field with the hostname/port from the request object. I'll look into this.

Re testing the validity of the swagger output: would be great to add. A possible approach might be to validate against the Swagger schema (perhaps by using the json-shema gem?) on the output. What do you think?

iNecas · 2017-11-09T16:05:11Z

Agreed with all you said :)

* moved EnumValidator#values to validator.rb * replaced 'save_and_compare' method with new rake task ("apipie:did_swagger_change") and optional 'x-computed-id' info field in output swagger * added "require 'zlib'" (if configured to generate x-computed-id field) * removed leftover routines (SwaggerGenerator#investigate, SwaggerGenerator#dump_param_desc) * added warning_inferring_boolean (when inferring that a [true,false] enum param is really a boolean) * documented the 'host' configuration param in the README, and made it possible not to include this field in the output

elasti-ron · 2017-11-13T16:59:49Z

Pushed a cleaned-up version addressing the code issues you highlighted.

Will keep you posted on progress re the /apidoc endpoint and the swagger schema validation.

elasti-ron · 2017-11-14T17:17:36Z

Hi @iNecas - it turns out that rendering at runtime from /apidoc is not as simple as I had hoped. It will take me some time before I'm able to look into this further, and I'll only be able to continue working on this (and on the swagger schema validation) next week.

If you feel comfortable with what I've posted so far as a first version, it might be best to merge that into the master branch and not wait for the additional functionality. This will reduce the risk of incompatibilities creeping into the code.

iNecas · 2017-11-14T19:48:59Z

I'm ok with waiting for the /apidoc endpoint, but I wukd lje to have the schema validator test before merging this to keep it working with the further updates

…enAPI-2.0 JSON schema

elasti-ron · 2017-11-15T10:05:07Z

The schema validation was surprisingly easy to add. Pushed a version that includes it.

…neration to play nice with swagger-codegen

elasti-ron · 2017-11-20T16:45:10Z

ping

elasti-ron · 2017-11-28T15:40:18Z

Hi @iNecas - runtime swagger generation is now supported (with some limitations - see the README).

iNecas · 2017-12-05T21:03:58Z

app/controllers/apipie/apipies_controller.rb

+
+      @language = get_language
+
+      Apipie.load_documentation if Apipie.configuration.reload_controllers? || (Rails.version.to_i >= 4.0 && !Rails.application.config.eager_load)


There is quite a lot of code duplicated from the index method. Could you look into how to DRY this a bit?

Otherwise, the implementation looks good and I think we are close to merging this

iNecas · 2017-12-11T11:18:53Z

lib/apipie/configuration.rb

+      @swagger_content_type_input = :form_data  # this can be :json or :form_data
+      @swagger_json_input_uses_refs = false
+      @swagger_include_warning_tags = false
+      @swagger_suppress_warnings = false #[105,100,102]


What does #[105,100,102] mean?

Nm: I looked at the readme and here we go :)

iNecas · 2017-12-11T11:22:39Z

Thanks @elasti-ron, I don't see any other reason why holding this in a PR any longer. Thanks for hard work and this one. I'm sure it will be useful for others as well

elasti-ron · 2017-12-25T16:09:07Z

Thanks @iNecas - it was good to collaborate with you on this.

As a next step, I'd like to add support for describing response structures, as it would make the output much more useful.

I've written a proposal to describe my suggested approach, and I would highly appreciate your feedback on it.

iNecas · 2018-01-02T11:13:57Z

Thanks for moving apipie forward. I would have few comments to the proposal: would you mind opening the proposal as a PR, with the markdown document in it. The would for the PR would not be to merge that, but to have a meaningful discussion over the diff itself.

In general, I like the idea of combining the concepts we already have in the apipie. Although, I would suggest introducing additional keyword (something like property) to the dsl: when defining response only keys, I'm not sure it makes sense to talk about parameter in that regard. It would be more like an alias.

I will have more comments, but I would like to leave that for a new PR to continue with the discussion.

iNecas · 2018-01-02T11:17:16Z

Also, make sure to advertise this in #273, as there are other folks interested into this functionality, that could have a valuable input to the progress of this.

elasti-ron · 2018-01-02T17:59:31Z

Done. #588.

elasti-ron added 3 commits November 7, 2017 13:49

Added Swagger generation

8ec66b3

fix for ruby versions < 2.2.3

8a15e0c

removed use of Array#to_h to support ruby 2.0.0

8445f6e

iNecas reviewed Nov 8, 2017

View reviewed changes

RSpec now includes validation of the generated swagger against the Op…

0fbe2fb

…enAPI-2.0 JSON schema

fixed 'warn_inferring_boolean' error. changed swagger operation-id ge…

a58cb72

…neration to play nice with swagger-codegen

elasti-ron added 3 commits November 28, 2017 17:12

fix: did not translate the resource description

50601d1

runtime swagger generation via ApipiesController

e9badda

removed debug prints in rspec

0e559b0

iNecas requested changes Dec 5, 2017

View reviewed changes

refactored runtime swagger generation in apipies_controller.rb (DRY)

b5531d8

iNecas reviewed Dec 11, 2017

View reviewed changes

iNecas merged commit 75a16bd into Apipie:master Dec 11, 2017

elasti-ron deleted the swagger_generation branch December 18, 2017 14:04

elasti-ron mentioned this pull request Jan 2, 2018

For discussion: proposal for describing responses #588

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added Swagger generation #569

Added Swagger generation #569

elasti-ron commented Nov 7, 2017 •

edited

Loading

iNecas Nov 8, 2017

iNecas Nov 8, 2017

iNecas Nov 8, 2017

iNecas Nov 8, 2017

iNecas commented Nov 8, 2017

iNecas commented Nov 8, 2017

iNecas commented Nov 8, 2017

elasti-ron commented Nov 9, 2017

iNecas commented Nov 9, 2017

elasti-ron commented Nov 13, 2017

elasti-ron commented Nov 14, 2017

iNecas commented Nov 14, 2017

elasti-ron commented Nov 15, 2017

elasti-ron commented Nov 20, 2017

elasti-ron commented Nov 28, 2017

iNecas Dec 5, 2017

iNecas Dec 11, 2017

iNecas Dec 11, 2017

iNecas commented Dec 11, 2017

elasti-ron commented Dec 25, 2017

iNecas commented Jan 2, 2018

iNecas commented Jan 2, 2018

elasti-ron commented Jan 2, 2018


		@language = get_language

		Apipie.load_documentation if Apipie.configuration.reload_controllers? \|\| (Rails.version.to_i >= 4.0 && !Rails.application.config.eager_load)

Added Swagger generation #569

Added Swagger generation #569

Conversation

elasti-ron commented Nov 7, 2017 • edited Loading

iNecas Nov 8, 2017

Choose a reason for hiding this comment

iNecas Nov 8, 2017

Choose a reason for hiding this comment

iNecas Nov 8, 2017

Choose a reason for hiding this comment

iNecas Nov 8, 2017

Choose a reason for hiding this comment

iNecas commented Nov 8, 2017

iNecas commented Nov 8, 2017

iNecas commented Nov 8, 2017

elasti-ron commented Nov 9, 2017

iNecas commented Nov 9, 2017

elasti-ron commented Nov 13, 2017

elasti-ron commented Nov 14, 2017

iNecas commented Nov 14, 2017

elasti-ron commented Nov 15, 2017

elasti-ron commented Nov 20, 2017

elasti-ron commented Nov 28, 2017

iNecas Dec 5, 2017

Choose a reason for hiding this comment

iNecas Dec 11, 2017

Choose a reason for hiding this comment

iNecas Dec 11, 2017

Choose a reason for hiding this comment

iNecas commented Dec 11, 2017

elasti-ron commented Dec 25, 2017

iNecas commented Jan 2, 2018

iNecas commented Jan 2, 2018

elasti-ron commented Jan 2, 2018

elasti-ron commented Nov 7, 2017 •

edited

Loading