github.com/rzurga/go-swagger@v0.28.1-0.20211109195225-5d1f453ffa3a/scan/doc.go (about)

     1  // +build !go1.11
     2  
     3  // Copyright 2015 go-swagger maintainers
     4  //
     5  // Licensed under the Apache License, Version 2.0 (the "License");
     6  // you may not use this file except in compliance with the License.
     7  // You may obtain a copy of the License at
     8  //
     9  //    http://www.apache.org/licenses/LICENSE-2.0
    10  //
    11  // Unless required by applicable law or agreed to in writing, software
    12  // distributed under the License is distributed on an "AS IS" BASIS,
    13  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14  // See the License for the specific language governing permissions and
    15  // limitations under the License.
    16  
    17  /*Package scan provides a scanner for go files that produces a swagger spec document.
    18  
    19  This package is intended for pre-go1.11 versions, and does not support go modules.
    20  
    21  You give it a main file and it will parse all the files that are required by that main
    22  package to produce a swagger specification.
    23  
    24  To use you can add a go:generate comment to your main file for example:
    25  
    26  		//go:generate swagger generate spec
    27  
    28  The following annotations exist:
    29  
    30  swagger:meta
    31  
    32  The swagger:meta annotation flags a file as source for metadata about the API.
    33  This is typically a doc.go file with your package documentation.
    34  
    35  You can specify a Consumes and Produces key which has a new content type on each line
    36  Schemes is a tag that is required and allows for a comma separated string composed of:
    37  http, https, ws or wss
    38  
    39  Host and BasePath can be specified but those values will be defaults,
    40  they should get substituted when serving the swagger spec.
    41  
    42  Default parameters and responses are not supported at this stage, for those you can edit the template json.
    43  
    44  swagger:strfmt [name]
    45  
    46  A swagger:strfmt annotation names a type as a string formatter. The name is mandatory and that is
    47  what will be used as format name for this particular string format.
    48  String formats should only be used for very well known formats.
    49  
    50  swagger:model [?model name]
    51  
    52  A swagger:model annotation optionally gets a model name as extra data on the line.
    53  when this appears anywhere in a comment for a struct, then that struct becomes a schema
    54  in the definitions object of swagger.
    55  
    56  The struct gets analyzed and all the collected models are added to the tree.
    57  The refs are tracked separately so that they can be renamed later on.
    58  
    59  When this annotation is found to be on an interface instead of a struct, the properties are provided
    60  through exported nullary methods.
    61  
    62  A property of an interface model can have a Discriminator: true annotation to mark that field as
    63  the field that will contain the discriminator value.
    64  
    65  swagger:route [method] [path pattern] [operation id] [?tag1 tag2 tag3]
    66  
    67  A swagger:route annotation links a path to a method.
    68  This operation gets a unique id, which is used in various places as method name.
    69  One such usage is in method names for client generation for example.
    70  
    71  Because there are many routers available, this tool does not try to parse the paths
    72  you provided to your routing library of choice. So you have to specify your path pattern
    73  yourself in valid swagger syntax.
    74  
    75  swagger:params [operationid1 operationid2]
    76  
    77  Links a struct to one or more operations. The params in the resulting swagger spec can be composed of several structs.
    78  There are no guarantees given on how property name overlaps are resolved when several structs apply to the same operation.
    79  This tag works very similarly to the swagger:model tag except that it produces valid parameter objects instead of schema
    80  objects.
    81  
    82  swagger:response [?response name]
    83  
    84  Reads a struct decorated with swagger:response and uses that information to fill up the headers and the schema for a response.
    85  A swagger:route can specify a response name for a status code and then the matching response will be used for that operation in the swagger definition.
    86  */
    87  package scan