Adding more docs to v2 swagger model.

once and done job, not much fun to be honest ;)

datamodel/high/v3/security_scheme.go

@@ -8,6 +8,16 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v3"
 )
 
+// SecurityScheme represents a high-level OpenAPI 3+ SecurityScheme object that is backed by a low-level one.
+//
+// Defines a security scheme that can be used by the operations.
+//
+// Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter),
+// mutual TLS (use of a client certificate), OAuth2’s common flows (implicit, password, client credentials and
+// authorization code) as defined in RFC6749 (https://www.rfc-editor.org/rfc/rfc6749), and OpenID Connect Discovery.
+// Please note that as of 2020, the implicit  flow is about to be deprecated by OAuth 2.0 Security Best Current Practice.
+// Recommended for most use case is Authorization Code Grant flow with PKCE.
+//  - https://spec.openapis.org/oas/v3.1.0#security-scheme-object
 type SecurityScheme struct {
 	Type             string
 	Description      string
@@ -21,6 +31,7 @@ type SecurityScheme struct {
 	low              *low.SecurityScheme
 }
 
+// NewSecurityScheme creates a new high-level SecurityScheme from a low-level one.
 func NewSecurityScheme(ss *low.SecurityScheme) *SecurityScheme {
 	s := new(SecurityScheme)
 	s.low = ss
@@ -38,6 +49,7 @@ func NewSecurityScheme(ss *low.SecurityScheme) *SecurityScheme {
 	return s
 }
 
+// GoLow returns the low-level SecurityScheme that was used to create the high-level one.
 func (s *SecurityScheme) GoLow() *low.SecurityScheme {
 	return s.low
 }