Method to add a specific path from the Phoenix routes to the Swagger map. Paths must enclose params with braces {var},
175 | rather than :var (http://swagger.io/specification/#pathTemplating)
Method to add a specific path from the Phoenix routes to the Swagger map. Paths must enclose params with braces {var},
388 | rather than :var (http://swagger.io/specification/#pathTemplating)
The SwaggerDoc module provides a convenience task for generating Swagger API documentation for Phoenix and Ecto-based projects. This task has been created for Phoenix and Ecto 1.0 and greater.
83 |
Getting Started
84 |
To use swaggerdoc with your projects, edit your mix.exs file and add it as a dependency:
85 |
defp deps do
86 | [{:swaggerdoc, "~> 0.0.1"}]
87 | end
In the browser of your choice, open the file temp folder/swagger-ui/dist/index.html
100 |
101 |
In the JSON API input box at the top of the page, paste in the link to the JSON
102 |
103 |
Hit the ‘Explore’ button
104 |
105 |
106 |
For a complete example, please see the examples section.
107 |
Config
108 |
SwaggerDoc’s version and project information is configured in your config.exs files. The options are specified under the :swaggerdoc application.
109 |
config :swaggerdoc,
110 | swagger_version: "2.0"
111 |
Task Config
112 |
The following task-specific options are available:
113 |
114 |
:output_path
115 |
116 |
Description: Specifies the file path where the JSON file will be created.
117 |
118 |
Type: string
119 |
120 |
Default Value: System.cwd!() <> “/swagger”
121 |
122 |
:output_file
123 |
124 |
Description: Specifies the file name (within the output_path) of the Swagger JSON
125 |
126 |
Type: string
127 |
128 |
Default Value: “api.json”
129 |
130 |
131 |
Swagger Config
132 |
The following Swagger-specific options are available:
133 |
134 |
:swagger_version
135 |
136 |
Description: Specifies the Swagger Specification version being used. It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be “2.0”.
137 |
Description: The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the host is not included, the host serving the documentation is to be used (including the port). The host does not support path templating.
147 |
Description: The base path on which the API is served, which is relative to the host. If it is not included, the API is served directly under the host. The value MUST start with a leading slash (/). The basePath does not support path templating.
157 |
Description: The transfer protocol of the API. Values MUST be from the list: “http”, “https”, “ws”, “wss”. If the schemes is not included, the default scheme to be used is the one used to access the Swagger definition itself.
167 |
Description: A list of MIME types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under Mime Types.
177 |
Description: A list of MIME types the APIs can produce. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under Mime Types.
187 |
The Phoenix Routes that is found via the Phoenix Router are converted into a Swagger Paths Object, each route becoming a Path Item. The Phoenix template paths are converted into Swagger path templates and each templated variable is converted into a Path paramter. All path parameters are assumed to be required and are of type string (except for parameters named id, which are assumed to be integers).
376 |
Response Definitions are generated, based on the HTTP verb associated with the operation:
377 |
378 |
All Verbs
379 |
380 |
“404” => %{“description” => “Resource not found”},
381 |
382 |
“401” => %{“description” => “Request is not authorized”},
383 |
384 |
“500” => %{“description” => “Internal Server Error”}
385 |
“400” => %{“description” => “Request contains bad values”}
399 |
400 |
PUT
401 |
402 |
“204” => %{“description” => “No Content”
403 |
404 |
“400” => %{“description” => “Request contains bad values”}
405 |
406 |
407 |
Customized Behavior
408 |
The default behavior of the task may be improved by adding action-specific functions that provide the task more detail. As the task scans for Phoenix Routes, it will check for the prescense of a function named “swaggerdoc_#{route.controller.method}”. If that function is present, the Map returned will be used in place of the default Swagger implementation. The map may consist of the following elements:
409 |
410 |
:description
411 |
412 |
Short description of the API endpoint.
413 |
414 |
:response_schema
415 |
416 |
For API endpoints that are returning a value (i.e. a GET), you may want to return a specific Schema Object that represents the return value.
417 |
418 |
To specify a specific Ecto Model, add as a $ref: "schema": %{"$ref": "#/definitions/HelloUser.User"}. Make sure to use the fully-qualified module name.
419 |
420 |
To specify an array of Ecto Models, add as an array of items: %{"title" => "Users", "type": "array", "items": %{"$ref": "#/definitions/HelloUser.User"}}
421 |
422 |
To specify a custom object that doesn’t have a corresponding model, build the schema directly:
423 |
424 |
425 |
%{
426 | "title" => "User.CustomFields", "type": "array", "items": %{
427 | "title" => "User.CustomField",
428 | "description" => "A Custom Field",
429 | "type" => "object",
430 | "required" => ["key","value"],
431 | "properties" => %{
432 | "key" => %{"type" => "string", "description" => "The key for the custom field"},
433 | "value" => %{"type" => "string", "description" => "The value for the custom field"},
434 | }
435 | }
436 | }
437 |
438 |
:parameters
439 |
440 |
An array of Parameter Definition objects. These values may represent a combination of query, body, formdata, etc… For an example, please see the sync_user:
441 |