github.com/ffalor/go-swagger@v0.0.0-20231011000038-9f25265ac351/generator/doc.go (about)

     1  // Copyright 2015 go-swagger maintainers
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //    http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  /*
    16  Package generator provides the code generation library for go-swagger.
    17  
    18  # Generating data types
    19  
    20  The general idea is that you should rarely see interface{} in the generated code.
    21  You get a complete representation of a swagger document in somewhat idiomatic go.
    22  
    23  To do so, there is a set of mapping patterns that are applied,
    24  to map a Swagger specification to go types:
    25  
    26  	   definition of primitive   => type alias/name
    27  	   definition of array       => type alias/name
    28  	   definition of map         => type alias/name
    29  
    30  	   definition of object
    31  	   with properties           => struct
    32  	   definition of $ref        => type alias/name
    33  
    34  	   object with only
    35  	   additional properties     => map[string]T
    36  
    37  	   object with additional
    38  	   properties and properties => custom serializer
    39  
    40  	   schema with schema array
    41  	   in items                  => tuple (struct with properties, custom serializer)
    42  
    43  	   schema with all of        => struct
    44  
    45  	     * allOf schema with $ref        => embedded value
    46  	     * allOf schema with properties  => properties are included in struct
    47  	     * adding an allOf schema with just "x-isnullable": true or
    48  		   "x-nullable": true turns the schema into a pointer when
    49  		   there are only other extension properties provided
    50  
    51  NOTE: anyOf and oneOf JSON-schema constructs are not supported by Swagger 2.0
    52  
    53  A property on a definition is a pointer when any one of the following conditions is met:
    54  
    55  	    it is an object schema (struct)
    56  	    it has x-nullable or x-isnullable as vendor extension
    57  	    it is a primitive where the zero value is valid but would fail validation
    58  		otherwise strings minLength > 0 or required results in non-pointer
    59  	    numbers min > 0, max < 0 and min < max
    60  
    61  JSONSchema and by extension Swagger allow for items that have a fixed size array,
    62  with the schema describing the items at each index. This can be combined with additional items
    63  to form some kind of tuple with varargs.
    64  
    65  To map this to go it creates a struct that has fixed names and a custom json serializer.
    66  
    67  NOTE: the additionalItems keyword is not supported by Swagger 2.0. However, the generator and validator parts
    68  in go-swagger do.
    69  
    70  # Documenting the generated code
    71  
    72  The code that is generated also gets the doc comments that are used by the scanner
    73  to generate a spec from go code. So that after generation you should be able to reverse
    74  generate a spec from the code that was generated by your spec.
    75  
    76  It should be equivalent to the original spec but might miss some default values and examples.
    77  */
    78  package generator