inaka / cowboy_swagger Goto Github PK

In the cowboy_swagger_handler the path "/[...]" added here should probably rather be "/api-docs/[...]". This would avoid confusion when performing a request to a nonexistent path.

Add a ktn_meta_SUITE-based test suite to this project.

Let users add definitions in code (can only be done now on sys.config) and add schemas to parameter fields.

It's possible to use another json library instead of jiffy?

Maybe the user could set it during the runtime or compile time.

Thanks.

The idea here is implement a Cowboy swagger handler to retrieve the swagger.json. In this case (initial version) the JSON will be generated during each request (that could be improved later). So the handle function should be able to:

• Call trails:all/0 to get defined trails
• With these trails, call swagger_json:from_trails(Trails) to generate the JSON and then return it.

Update documentation to inform that Erlang 18+ is required for the release 0.1.0

Regardless of what I add to the trails metadata for my endpoints, swagger always try to send contents as application/json:

The package on https://hex.pm/packages/cowboy_swagger doesn't expose the dependencies like trail.

It currently is

-spec validate_metadata(trails:metadata()) -> trails:metadata().

It should be

-spec validate_metadata(trails:metadata(_)) -> metadata().

I ran some compliance issues which can be fixed in the examples section (how to use cowboy-swagger), or in the code itself (what cowboy-swagger generates).

• in the info object version of the api is required (there should be some generated version in default)
• swagger editor [1] also complained about the missing basePath. Even when I specified basePath in the app.config I didn't see in the json, probably it didn't pick up the value.
• a path parameter needs a type field (it seems to be required), it can be string or number see spec [2]. format which is optional but in numeric cases would be good to see an example.
• when responses are needed, it needs at least:

"responses": {
    "default": {
        "description": ""
    }
}

but one can specify schema per http response code. See links below [2].

• For body parameters I needed to define a "schema": {} at least, in order that the JSON would be compliant. required is not required here, type is forbidden.

I didn't have time to discover all parts of schema, but it would be a good example how to define request bodies which conform to a json.

[1] http://editor.swagger.io/#/
[2] http://swagger.io/specification/

Modify cowboy_swagger_handler to return either swagger.json or swagger.yaml.

Fix trails routes for:

• Static content (Swagger-UI). What should be the path here? We should avoid any routes conflicts.
• cowboy_swagger_handler. The path here should be /swagger.json directly.

NOTE: The idea is let that path totally configurable, as an environment variable of the app, and default value would be /.

E.g. a cowboy binding :id must have a corresponding Swagger parameter named id.

Current behaviour is that such constraint is not enforced hence cowboy_swagger generates /api-docs/swagger.json for UI accessible at /api-docs with path that may contain bindings with no corresponding parameter, hence causing curly variable template to be sent to server.

Example: trail with cowboy binding called :id and swagger parameter named key causes this Swagger UI...

... that when clicking Try it out! sends to server something like /places/{id} - i.e. with no replaced value:

2017-03-09 13:15:16.503 [info] <0.942.0> PUT /places/%7Bid%7D

• Download the latest Swagger UI release, but just the static Swagger UI code, which is located in: https://github.com/swagger-api/swagger-ui/tree/master/dist/
• Put the content of the downloaded folder within priv/swagger

My rebar.config is:

{deps, [
      {cowboy_swagger, "0.1.1"}
]}.
``

joaohf@porco:~/p/x$ make
===> Verifying dependencies...
===> Package inaka_mixer-0.1.4 not found. Fetching registry updates and trying again...
===> Updating package registry...
===> Writing registry to /home/joaohf/.cache/rebar3/hex/default/registry
===> Generating package index...
===> Writing index to /home/joaohf/.cache/rebar3/hex/default/packages.idx
===> Package not found in registry: inaka_mixer-0.1.4.
Makefile:10: recipe for target 'compile' failed
make: *** [compile] Error 1

$ rebar3 hex search swagger
cowboy_swagger: 0.1.1
$ rebar3 hex search mixer
inaka_mixer: 0.1.5

esl/TODO#60

Migrate to rebar3 as described here.

This is requested by esl/TODO#62

For consistency, it should be https://github.com/inaka/cowboy_swagger/

And remember to update the Readme!

Do whatever it takes to appears cowboy-swagger on "http://swagger.io/open-source-integrations/"

I've created a branch for upgrading to new cowboy 2 API:
https://github.com/jeanparpaillon/cowboy-swagger/tree/cowboy2

According what I learned, the cowboy REST are not directly define the HTTP method such as "PUT", "GET", "POST", It uses the methods such as allowed_methods. I just wander that this app can supports the cowboy REST.
Thanks a lot.

Right now, it only accepts strings that it checks with io_lib:printable_list/1

The idea is validate and set default values in required/mandatory fields within cowboy_swagger:metadata(), according with swagger schema (http://swagger.io/specification).

For example, swagger_parameters() has 2 required fields name and in, so in case those fields aren't specified in cowboy_swagger:metadata(), default values should be set.

Even when #22 is fixed by just setting basePath => "", sometimes having a basePath (e.g. /admin/api) is actually useful, but swagger has to consider that such a basePath will be included in the trails routes, at least until inaka/cowboy-trails#22 is implemented. And in that case, basePath should be taken from there and not as an extra swagger property.

As described on esl/TODO#62 and #68's comment by @hcs42

Make calls to /api-docs be redirected to /api-docs/index.html in order to properly render swagger assets.

Currently, the example (https://github.com/inaka/cowboy-swagger/tree/master/example), is pointing to an old version of cowboy-swagger (0.0.1). The idea is point to the latest one.

Within the module cowboy_swagger implement:

-spec to_json(Trails :: [trails:trail()]) -> Json :: binary().

jiffy application is missing from application section in .app.src file

Once inaka/cowboy-trails#19 is done, we can do the same here.

The Cowboy swagger handler (swagger_handler) must implement the callback trails_handler:trails/0 from behaviour trails_handler. This function must return the Cowboy routes related to: static content (Swagger-UI) and the handler itself (swagger_handler).

since it seems to be migrated to rebar3, also update the README, if you follow the current steps it doesn't work (make can't be called)

These two:

The idea of this handler is return the index.html contained within priv/swagger

Hi !

When I followed instructions in README about creating schema then my swagger ui didn't work. It worked when I changed maps keys and values to binary string. So only the following configuration worked for me:

option 1:

`[ ... % other configurations
, { cowboy_swagger
  , [ { global_spec
      , #{ swagger => "2.0"
         , info => #{title => "My app API"}
         , definitions => #{
             <<"RequestBody">> =>
               #{ <<"name">> =>
                   #{ <<"type" => <<"string">>
                    , <<"description">> => <<"Newspaper name">>
                    }
                , <<"description">> =>
                        #{ <<"type" =><< "string">>
                     , <<"description">> => <<"Newspaper description">>
                    }
                }
           }
         }
      }
    ]
  }
]`

option2:

`-spec trails() -> trails:trails().
trails() ->
  DefinitionName = <<"RequestBody">>,
  DefinitionProperties =
    #{ <<"name">> =>
         #{ <<"type">> => <<"string">>
          , <<"description">> => <<"Newspaper name">>
          }
     , <<"description">> =>
         #{ <<"type">> => <<"string">>
          , <<"description">> => <<"Newspaper description">>
          }
     },
  % Add the definition
  ok = cowboy_swagger:add_definition(DefinitionName, DefinitionProperties),
  ...`

Is it a bug in README or maybe something has changed and broke the configuration?

location in Response Headers should be:
"/newspapers/newspaper1/news/1b62ce01-59a2-4e70-8388-88d264ae0f72"*
instead of:
"/newspapers/:news/news/1b62ce01-59a2-4e70-8388-88d264ae0f72"*

Files in releases are placed under lib/cowboy_swagger-…/….
The proper way to find that path would be:

filename:join(code:priv_dir(cowboy_swagger), "swagger")

Introduction

This is the list of things to check for every open-source project that we create

Usage

Each project should have a github repo with github issues enabled. As the main dev in that project, you should make sure to have the corresponding items from the lists below reported as issues there and work on having them implemented/done before releasing the 1.0 version of your product.

General Items

• It has a github repo
• It has a proper Apache2 LICENSE file
  • with the proper copyright: 2015 Erlang Solutions Ltd.
• It's has a clear and useful README.md
• It's documented (with examples)
• It's tested
• It's hooked to a the open-source hipchat room
• It has a link to the open-source hipchat room in its README
• It has a link to inaka.github.io in its README and/or landing page

Exhibition

• There is a blog post about it
• It's shared on social networks
• It's shared on reddit
• It's shared on hacker news with a title like Show HN: description
• It has a landing page built in github pages

For Libraries

• It provides a sample application
• Examples of use are documented in the README or linked from there

For Erlang Projects

• It's checked with Gadget
• It's shared on Erlang Central