github.com/anchorlabsinc/go-swagger@v0.19.0/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 /*Package generator provides the code generation library for go-swagger. 16 17 Generating data types 18 19 The general idea is that you should rarely see interface{} in the generated code. 20 You get a complete representation of a swagger document in somewhat idiomatic go. 21 22 To do so, there is a set of mapping patterns that are applied, 23 to map a Swagger specification to go types: 24 25 definition of primitive => type alias/name 26 definition of array => type alias/name 27 definition of map => type alias/name 28 29 definition of object 30 with properties => struct 31 definition of $ref => type alias/name 32 33 object with only 34 additional properties => map[string]T 35 36 object with additional 37 properties and properties => custom serializer 38 39 schema with schema array 40 in items => tuple (struct with properties, custom serializer) 41 42 schema with all of => struct 43 44 * allOf schema with $ref => embedded value 45 * allOf schema with properties => properties are included in struct 46 * adding an allOf schema with just "x-isnullable": true or 47 "x-nullable": true turns the schema into a pointer when 48 there are only other extension properties provided 49 50 NOTE: anyOf and oneOf JSON-schema constructs are not supported by Swagger 2.0 51 52 A property on a definition is a pointer when any one of the following conditions is met: 53 54 it is an object schema (struct) 55 it has x-nullable or x-isnullable as vendor extension 56 it is a primitive where the zero value is valid but would fail validation 57 otherwise strings minLength > 0 or required results in non-pointer 58 numbers min > 0, max < 0 and min < max 59 60 JSONSchema and by extension Swagger allow for items that have a fixed size array, 61 with the schema describing the items at each index. This can be combined with additional items 62 to form some kind of tuple with varargs. 63 64 To map this to go it creates a struct that has fixed names and a custom json serializer. 65 66 NOTE: the additionalItems keyword is not supported by Swagger 2.0. However, the generator and validator parts 67 in go-swagger do. 68 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 package generator