swagger_yard 0.4.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75d0e74a6ac517d09a0743edffa6ea2aa7ddf963
-  data.tar.gz: cbda242b96ac6e12646362d573f93b6becc050d9
+  metadata.gz: 9e95fe3850f449db0d3234e6b314bf76c3570f7d
+  data.tar.gz: 9f2e1c1a9d2a3731431e6d606a4023d7ae692326
 SHA512:
-  metadata.gz: 52ed18981ab935c658185407e57a65b70c8ecd711c844d1dcfd84dee2c21064dc98717d498f8101d169ed6bd9cf4fb9a80e4f6f442491d76919523d84f5cea90
-  data.tar.gz: ab50c39b04875a413514fda5a8ece2d021421768f97a42009f52fdc0f30f940bd910272f598efae73690cfa4054db4e3386d43622f02968c66dbc9ab8b6396ae
+  metadata.gz: 3609ee174c38e70038f0358b735c9c1ffdf73ca76c634d9e2f93f1d42f497d6f752b3cf0b1c9f18d58ce68ff426d8f254b09fb76da748dc8f2a5e87d3ea85b38
+  data.tar.gz: de11893ad4b1293ad2955617ebd967c2030d7347beb15ea6ac486de6769f0a12fa2e334822dae4c2790b2c83b95abe8f251f12cce897209bab2106d9d1217bd5

data/README.md

@@ -1,6 +1,6 @@
-# SwaggerYard [![Build Status](https://travis-ci.org/livingsocial/swagger_yard.svg?branch=master)](https://travis-ci.org/tpitale/swagger_yard) #
+# SwaggerYard [![Build Status](https://travis-ci.org/livingsocial/swagger_yard.svg?branch=master)](https://travis-ci.org/livingsocial/swagger_yard) #
 
-SwaggerYard is a gem to convert extended YARD syntax comments into the swagger spec compliant json format.
+SwaggerYard is a gem to convert custom YARD tags in comments into Swagger 2.0 or OpenAPI 3.0.0 specs.
 
 ## Installation ##
 
@@ -15,89 +15,52 @@ Install the gem with Bunder:
 
 ## Getting Started ##
 
-### Place configuration in a rails initializer ###
+Place configuration in a Rails initializer or suitable configuration file:
 
     # config/initializers/swagger_yard.rb
     SwaggerYard.configure do |config|
       config.api_version = "1.0"
-      config.reload = Rails.env.development?
+
+      config.title = 'Your API'
+      config.description = 'Your API does this'
 
       # where your actual api is hosted from
       config.api_base_path = "http://localhost:3000/api"
-    end
-
-## SwaggerYard Usage ##
-
-### Types ###
 
-Types of things (parameters or responses of an operation, properties of a model)
-are indicated inside square-brackets (e.g., `[string]`) as part of a YARD tag.
+      # Where to find controllers (can be an array of paths/globs)
+      config.controller_path = ::Rails.root + 'app/controllers/**/*'
 
-- Model references should be Capitalized or CamelCased by convention.
-- Basic types (integer, boolean, string, object, number, date, time, date-time,
-  uuid, etc.) should be lowercased.
-- An array of models or basic types is specified with `[array<...>]`.
-- An enum of allowed string values is specified with `[enum<one,two,three>]`.
-- An object definition can include the property definitions of its fields, and / or of an additional property for any remaining allowed fields. E.g., `[object<name: string, age: integer,  string >]`
-- Structured data like objects, arrays, pairs, etc., definitions can also be nested; E.g., `[object<pairs:array<object<right:integer,left:integer>>>]`
-- JSON-Schema `format` attributes can be specified for basic types using
-  `<...>`. For example, `[integer<int64>]` produces JSON
-  `{ "type": "integer", "format": "int64" }`.
-- Regex pattern constraints can be specified for strings using
-  `[regex<PATTERN>]`. For example, `[regex<^.{3}$>]` produces JSON
-  `{ "type": "string", "pattern": "^.{3}$" }`.
-
-### External Schema ###
+      # Where to find models (can be an array)
+      config.model_path = ::Rails.root + 'app/decorators/**/*'
+    end
 
-Types can be specified that refer to external JSON schema documents for their definition. External schema documents are expected to also define their models under a `definitions` top-level key like so:
-```
-{
-  "definitions": {
-    "MyStandardModel": {
-    }
-  }
-}
-```
+Then start to annotate controllers and models as described below.
 
-To register an external schema so that it can be referenced in places where you specify a type, configure SwaggerYard as follows:
-```ruby
-SwaggerYard.configure do |config|
-  config.external_schema mymodels: 'https://example.com/mymodels/v1.0'
-end
-```
+### Generate Specification ###
 
-Then refer to models in the schema using the syntax `[mymodels#MyStandardModel]` where types are specified. This causes SwaggerYard to emit the following schema for the type:
+To generate a Swagger or OpenAPI specification, use one of the `SwaggerYard::Swagger` or `SwaggerYard::OpenAPI` classes as follows in a script or Rake task (or use [swagger_yard-rails](/livingsocial/swagger_yard-rails)):
 
 ```
-{ "$ref": "https://example.com/mymodels/v1.0#/definitions/MyStandardModel" }
+spec = SwaggerYard::OpenAPI.new
+# Generate YAML
+File.open("openapi.yml", "w") { |f| f << YAML.dump(spec.to_h) }
+# Generate JSON
+File.open("openapi.json, "w") { |f| f << JSON.pretty_generate(spec.to_h) }
 ```
 
-### Options ###
+## Documenting APIs
 
-Parameter or property _options_ are expressed inside parenthesis immediately
-following the parameter or property name.
+Documenting controllers and models is best illustrated by example.
 
-Examples:
+### Controller ###
 
-	# @parameter name(required) [string]  Name of the package
-	# @parameter age(nullable)  [integer] Age of package
-	# @parameter package(body)  [Package] Package object
+Each Swagger-ized controller must have a `@resource` tag naming the API to be documented. Without this tag, no endpoints will be generated.
 
-Possible parameters include:
-
-- `required`: indicates a required parameter or property.
-- `nullable`: indicates that JSON `null` is an allowed value for the property.
-- `multiple`: indicates a parameter may appear multiple times (usually in a
-  query string, e.g., `param=a&param=b&param=c`)
-- `body`/`query`/`path`/`formData`: Indicates where the parameter is located.
-
-### Example of using SwaggerYard in a Controller ###
+Then, document each controller action method that is an endpoint of the API. Each endpoint needs to have a `@path` tag at a minimum. `@parameter` tags and `@response_type`/`@response` tags specify the inputs and outputs to the endpoint. A request body is specified with the use of a single `@parameter` tag with a `(body)` option. (`@response_type` is shorthand for the type of the default response, while `@response` allows you to specify the HTTP status.)
 
 ```ruby
 # @resource Account ownership
 #
-# @resource_path /accounts/ownerships
-#
 # This document describes the API for creating, reading, and deleting account ownerships.
 #
 class Accounts::OwnershipsController < ActionController::Base
@@ -118,7 +81,6 @@ class Accounts::OwnershipsController < ActionController::Base
   # @parameter end_at_less        [date]        Filters response to include only items with end_at <= specified timestamp (e.g. end_at_less=2012-02-15T02:06:56Z).
   #
   def index
-    ...
   end
 
   ##
@@ -126,16 +88,26 @@ class Accounts::OwnershipsController < ActionController::Base
   #
   # @path [GET] /accounts/ownerships/{id}
   # @response_type [Ownership]
-  # @error_message [EmptyOwnership] 404 Ownership not found
-  # @error_message 400 Invalid ID supplied
+  # @response [EmptyOwnership] 404 Ownership not found
+  # @response 400 Invalid ID supplied
   #
   def show
-    ...
+  end
+
+  ##
+  # Creates an ownership for an account
+  #
+  # @path [POST] /accounts/ownerships
+  # @parameter ownership(body) [Ownership] The ownership to be created
+  # @response_type [Ownership]
+  def create
   end
 end
 ```
 
-### Example of using SwaggerYard in a Model ###
+### Model ###
+
+Each model to be exposed in the specification must have a `@model` tag. Model properties are specified with `@property` tags.
 
 ```ruby
 #
@@ -192,10 +164,132 @@ module Models
 end
 ```
 
+### Types ###
+
+Types of things (parameters or responses of an operation, properties of a model) are indicated inside square-brackets (e.g., `[string]`) as part of a YARD tag.
+
+- Model references should be Capitalized or CamelCased by convention.
+- Basic types (integer, boolean, string, object, number, date, time, date-time, uuid, etc.) should be lowercased.
+- An array of models or basic types is specified with `[array<...>]`.
+- An enum of allowed string values is specified with `[enum<one,two,three>]`.
+- An object definition can include the property definitions of its fields, and / or of an additional property for any remaining allowed fields. E.g., `[object<name: string, age: integer,  string >]`
+- Structured data like objects, arrays, pairs, etc., definitions can also be nested; E.g., `[object<pairs:array<object<right:integer,left:integer>>>]`
+- JSON-Schema `format` attributes can be specified for basic types using `<...>`. For example, `[integer<int64>]` produces JSON `{ "type": "integer", "format": "int64" }`.
+- Regex pattern constraints can be specified for strings using `[regex<PATTERN>]`. For example, `[regex<^.{3}$>]` produces JSON `{ "type": "string", "pattern": "^.{3}$" }`.
+
+### Options ###
+
+Parameter or property _options_ are expressed inside parenthesis immediately
+following the parameter or property name.
+
+Examples:
+
+    # @parameter name(required) [string]  Name of the package
+    # @parameter age(nullable)  [integer] Age of package
+    # @parameter package(body)  [Package] Package object
+
+Possible parameters include:
+
+- `required`: indicates a required parameter or property.
+- `nullable`: indicates that JSON `null` is an allowed value for the property.
+- `multiple`: indicates a parameter may appear multiple times (usually in a
+  query string, e.g., `param=a&param=b&param=c`)
+- `body`/`query`/`path`/`formData`: Indicates where the parameter is located.
+
+### Examples
+
+The Swagger and OpenAPI specs both allow for [specifying example data](https://swagger.io/docs/specification/adding-examples/) at multiple levels. SwaggerYard allows you to use an `@example` tag to specify example JSON data at the response, model, and individual property levels.
+
+The basic format of an `@example` is:
+
+```ruby
+# @example [name]
+#    body content
+#    should be indented
+#    and can span
+#    multiple lines
+```
+
+#### Response examples
+
+Response examples should appear in a method documentation block inside a controller, alongside the parameters and response tags. Use a named `@example` to associate the example with a specific response, or use an unnammed example to associate the data to the default response (when using a `@response_type` tag).
+
+```ruby
+  # return a Pet
+  # @path [GET] /pets/{id}
+  # @parameter id [integer] The ID for the Pet
+  # @response_type [Pet]
+  # @response [ErrorPet] 404 Pet not found
+  # @example
+  #    {"id": 1, "names": ["Fido"], "age": 12}
+  # @example 404
+  #    {"error": 404, "message": "Pet not found"}
+  def show
+  end
+```
+
+#### Model examples
+
+Use a model example to specify an example for the entire model at once. The example tag should omit any name to associate the data with the model itself and not a single property.
+
+```ruby
+# @model
+# @property id(required)  [integer]
+# @property name          [string]
+# @example
+#   {"id": 42, "name": "Fred Flintstone"}
+class Person
+end
+```
+
+### Property examples
+
+Use property examples to specify data for individual properties. To associate the example data, the `@example` tag must use the same name as the property and appear _after_ the property.
+
+```ruby
+# @model
+# @property id(required)  [integer]
+# @example id
+#    42
+# @property name          [string]
+# @example name
+#   "Fred Flintstone"
+class Person
+end
+```
+
+
+### External Schema ###
+
+Types can be specified that refer to external JSON schema documents for their definition. External schema documents are expected to also define their models under a `definitions` top-level key like so:
+```
+{
+  "definitions": {
+    "MyStandardModel": {
+    }
+  }
+}
+```
+
+To register an external schema so that it can be referenced in places where you specify a type, configure SwaggerYard as follows:
+```ruby
+SwaggerYard.configure do |config|
+  config.external_schema mymodels: 'https://example.com/mymodels/v1.0'
+end
+```
+
+Then refer to models in the schema using the syntax `[mymodels#MyStandardModel]` where types are specified. This causes SwaggerYard to emit the following schema for the type:
+
+```
+{ "$ref": "https://example.com/mymodels/v1.0#/definitions/MyStandardModel" }
+```
+
+
 ## Authorization ##
+
 ### API Key auth ###
 
-SwaggerYard supports API Key auth descriptions. Start by adding `@authorization` to your `ApplicationController`.
+SwaggerYard supports several authorization styles. Start by adding `@authorization` to your `ApplicationController`.
 
 ```ruby
 #
@@ -205,7 +299,7 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-Then you can use these authorizations from your controller or actions in a controller. The name comes from either header or query plus the name of the key downcased/underscored.
+Then you can use these authorizations from your controller or actions in a controller.
 
 ```ruby
 #
@@ -215,16 +309,38 @@ class PetController < ApplicationController
 end
 ```
 
-### Custom security definitions (OAuth2) ###
+Supported formats for the `@authorization` tag are as follows:
+
+```ruby
+# @authorization [apiKey] (query|header|cookie) key-name The rest is a description
+# @authorization [bearer] mybearerauth bearer-format The rest is a description
+# @authorization [basic] mybasicauth The rest is a description
+# @authorization [digest] digestauth The rest is a description
+# @authorization [<any-rfc7235-auth>] myrfcauth The rest is a description
 
-Additionally SwaggerYard also supports custom [security definitions](http://swagger.io/specification/#securityDefinitionsObject). You can define these in your configuration like:
+- For `apiKey` the name of the authorization is formed as `"#{location}_#{key_name}".downcase.gsub('-','_')`.
+  Example: `@authorization [apiKey] header X-API-Key` is named `header_x_api_key`. (This naming scheme is kept for backwards compatibility.)
+
+- All others are named by the tag name following the `[type]`.
+  Example: `@authorization [bearer] myBearerAuth Format Description` is named `myBearerAuth`.
+
+### Custom security schemes ###
+
+SwaggerYard also supports custom [security schemes](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#security-scheme-object). You can define these in your configuration like:
 
 ```ruby
 SwaggerYard.configure do |config|
-  config.security_definitions['petstore_oauth'] = {
+  config.security_schemes['petstore_oauth'] = {
     type: "oauth2",
-    authorizationUrl: "http://swagger.io/api/oauth/dialog",
-    flow: :implicit
+    flows: {
+      implicit: {
+        authorizationUrl: "http://swagger.io/api/oauth/dialog",
+        scopes: {
+          "write:pets": "modify pets in your account",
+          "read:pets": "read your pets"		
+        }
+      }
+    }
   }
 end
 ```
@@ -237,38 +353,11 @@ class PetController < ApplicationController
 end
 ```
 
-## UI ##
-
-We suggest using something like [swagger-ui_rails](https://github.com/3scale/swagger-ui_rails/tree/dev-2.1.3) for your UI needs inside of Rails.
 
-To generate JSON from your code on request, checkout the [swagger_yard-rails](https://github.com/livingsocial/swagger_yard-rails) project. This provides an engine to parse and render the json required for use by swagger-ui_rails.
-
-## More Information ##
-
-* [swagger-ui_rails](https://github.com/3scale/swagger-ui_rails/tree/dev-2.1.3)
-* [swagger_yard-rails](https://github.com/livingsocial/swagger_yard-rails)
-* [Swagger-spec version 2.0](https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md)
-* [Yard](https://github.com/lsegal/yard)
+### Better Rails integration with swagger_yard-rails
 
-## Current Parsing "Tree" Structure ##
+To generate specifications from your Rails app on request, check out the [swagger_yard-rails](https://github.com/livingsocial/swagger_yard-rails) project. This provides an engine that has a mountable endpoint that will parse the source code and render the specification as a json document.
 
-```
-ResourceListing
-|
--> ApiDeclaration (controller)
-| |
-| -> ListingInfo (controller class)
-| -> Authorization (header/param for auth, also added to ResourceListing?)
-| -> Api(s) (controller action, by path)
-|   |
-|   -> Operation(s) (controller action with HTTP method)
-|     |
-|     -> Parameter(s) (action param)
-|
--> Model (model)
-  |
-  -> Properties (model attributes)
-```
 
 ### Path Discovery Function ##
 
@@ -281,7 +370,7 @@ any can be determined.
 SwaggerYard.configure do |config|
   config.path_discovery_function = ->(yard_obj) do
     # code here to inspect the yard doc object
-	# and return a [method, path] for the api
+    # and return a [method, path] for the api
   end
 end
 ```
@@ -289,4 +378,14 @@ end
 In [swagger_yard-rails][], this hook is used to set a function that inspects the
 Rails routing tables to reverse look up and compute paths.
 
+
+## More Information ##
+
+* [swagger_yard-rails][]
+* [Swagger-spec version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)
+* [OpenAPI version 3.0.0](https://swagger.io/docs/specification/about/)
+* [Yard](https://github.com/lsegal/yard)
+
+
 [swagger_yard-rails]: https://github.com/livingsocial/swagger_yard-rails
+

data/lib/swagger_yard.rb

@@ -3,15 +3,17 @@ require "json"
 require "swagger_yard/configuration"
 require "swagger_yard/type"
 require "swagger_yard/type_parser"
+require "swagger_yard/example"
 require "swagger_yard/parameter"
 require "swagger_yard/property"
 require "swagger_yard/operation"
 require "swagger_yard/authorization"
-require "swagger_yard/resource_listing"
-require "swagger_yard/api_declaration"
+require "swagger_yard/specification"
+require "swagger_yard/api_group"
 require "swagger_yard/model"
-require "swagger_yard/api"
+require "swagger_yard/path_item"
 require "swagger_yard/swagger"
+require "swagger_yard/openapi"
 
 module SwaggerYard
   class Error < StandardError; end
@@ -98,11 +100,11 @@ module SwaggerYard
     # Register some custom yard tags used by swagger-ui
     def register_custom_yard_tags!
       ::YARD::Tags::Library.define_tag("Api resource", :resource)
-      ::YARD::Tags::Library.define_tag("Resource path", :resource_path) # TODO: remove deprecated tag
       ::YARD::Tags::Library.define_tag("Api path", :path, :with_types)
       ::YARD::Tags::Library.define_tag("Parameter", :parameter, :with_types_name_and_default)
       ::YARD::Tags::Library.define_tag("Response type", :response_type, :with_types)
       ::YARD::Tags::Library.define_tag("Error response message", :error_message, :with_types_and_name)
+      ::YARD::Tags::Library.define_tag("Response", :response, :with_types_and_name)
       ::YARD::Tags::Library.define_tag("Api Summary", :summary)
       ::YARD::Tags::Library.define_tag("Model resource", :model)
       ::YARD::Tags::Library.define_tag("Model superclass", :inherits)
@@ -110,6 +112,8 @@ module SwaggerYard
       ::YARD::Tags::Library.define_tag("Model discriminator", :discriminator, :with_types_name_and_default)
       ::YARD::Tags::Library.define_tag("Authorization", :authorization, :with_types_and_name)
       ::YARD::Tags::Library.define_tag("Authorization Use", :authorize_with)
+      # @example is a core YARD tag, let's use it
+      # ::YARD::Tags::Library.define_tag("Example", :example, :with_title_and_text)
     end
   end
 end