github.com/josephspurrier/go-swagger@v0.2.1-0.20221129144919-1f672a142a00/docs/use/spec.md (about)

     1  # swagger.json generation
     2  
     3  The toolkit has a command that will let you generate a swagger spec document from your code.
     4  The command integrates with go doc comments, and makes use of structs when it needs to know of
     5  types.
     6  
     7  Based on the work from https://github.com/yvasiyarov/swagger.
     8  
     9  It uses a similar approach but with expanded annotations and it produces a swagger 2.0 spec.
    10  
    11  The goal of the syntax is to make it look as a natural part of the documentation for the application code.
    12  
    13  The generator is passed a main package and it uses that to discover all the code in use.
    14  To do this it makes use of go's loader package. The same package that is used by tools like goimports to discover which files to format.
    15  
    16  Once the parser has encountered a comment that matches on of its known tags, the parser will assume that the rest of the comment block is for swagger.
    17  
    18  If it is your first time using this library for generating swagger 
    19  specification, you can also take a look at 
    20  [this getting started guide](https://medium.com/@pedram.esmaeeli/generate-swagger-specification-from-go-source-code-648615f7b9d9?source=friends_link&sk=b402acc563e8d2bfadd1ac02abddc3bb)
    21  on Medium to get the big picture and then return here to read more 
    22  about all annotations and commands provided by this package.
    23  
    24  ### Usage
    25  
    26  To generate a spec:
    27  
    28  ```
    29  swagger generate spec -o ./swagger.json
    30  ```
    31  
    32  See the full list of available options [here](../generate/spec.md).
    33  
    34  You give it a main file and it will parse all the files that are reachable by that main
    35  package to produce a swagger specification.
    36  
    37  To use you can add a go:generate comment to your main file for example:
    38  
    39  ```
    40  //go:generate swagger generate spec
    41  ```
    42  
    43  The command requires a main package or file and it wants your code to compile. It uses the go tools loader to load an application and then scans all the packages that are in use by the code base.
    44  This means that for something to be discoverable it needs to be reachable by a code path triggered through the main package.
    45  
    46  If an annotation is not yet supported or you want to merge with a pre-existing spec, you can use the -i parameter.
    47  
    48  ```
    49  swagger generate spec -i ./swagger.yml -o ./swagger.json
    50  ```
    51  
    52  The idea is that there are certain things that are more easily expressed by just using yaml
    53  
    54  To generate spec in yaml format, just name the output file with ".yml" or ".yaml" extension. For example:
    55  
    56  ```
    57  swagger generate spec -o ./swagger.yml
    58  ```
    59  
    60  If you don't want to generate Go language specific extensions in the spec file, you can disable them by doing
    61  
    62  ```
    63  SWAGGER_GENERATE_EXTENSION=false && swagger generate spec -o ./swagger.yml
    64  ```
    65  
    66  #### Parsing rules
    67  
    68  ![warning](../warning.png)This command relies heavily on the way godoc works.
    69  
    70  ![warning](../warning.png)This means you should be very aware of all the things godoc supports.
    71  
    72  * [godoc documenting go code](http://blog.golang.org/godoc-documenting-go-code)
    73  * [godoc ToHTML](https://golang.org/pkg/go/doc/#ToHTML)
    74  * [commenting go effectively](https://golang.org/doc/effective_go.html#commentary)
    75  * [godoc documentation](https://godoc.org/golang.org/x/tools/cmd/godoc)
    76  
    77  Single page which documents all the currently supported godoc rules:
    78  
    79  * [godoc tricks](https://godoc.org/github.com/fluhus/godoc-tricks)
    80  
    81  The generated code tries to avoid golint errors.
    82  
    83  * [go lint](https://github.com/golang/lint)
    84  * [go lint style guide](https://github.com/golang/go/wiki/CodeReviewComments)
    85  
    86  When an object has a title and a description field, it will use the go rules to parse those. So the first line of the
    87  comment block will become the title, or a header when rendered as godoc. The rest of the comment block will be treated
    88  as description up to either the end of the comment block, or a line that starts with a known annotation.
    89  
    90  #### Annotation syntax
    91  
    92  If you want to exclude something from the spec generation process you can try with the struct tag: `json:"-"`
    93  
    94  There are several annotations that mark a comment block as a participant for the swagger spec.
    95  
    96  - [swagger:meta](../use/spec/meta.md)
    97  - [swagger:route](../use/spec/route.md)
    98  - [swagger:parameters](../use/spec/params.md)
    99  - [swagger:response](../use/spec/response.md)
   100  - [swagger:operation](../use/spec/operation.md)
   101  - [swagger:model](../use/spec/model.md)
   102  - [swagger:allOf](../use/spec/allOf.md)
   103  - [swagger:strfmt](../use/spec/strfmt.md)
   104  - [swagger:discriminated](../use/spec/discriminated.md)
   105  - [swagger:ignore](../use/spec/ignore.md)
   106  
   107  #### Embedded types
   108  
   109  For the embedded schemas there are a set of rules for the spec generator to vary the definition it generates.
   110  When an embedded type isn't decorated with the `swagger:allOf` annotation, then the properties from the embedded value will be included in the generated definition as if they were defined on the definition. But when the embedded type is decorated with the `swagger:allOf` annotation then the all of element will be defined as a "$ref" property instead. For an annotated type there is also the possibility to specify an argument, the value of this argument will be used as the value for the `x-class` extension. This allows for generators that support the
   111  `x-class` extension to reliably build a serializer for a type with a discriminator
   112  
   113  #### Known vendor extensions
   114  
   115  There are a couple of commonly used vendor extensions that most frameworks support to add functionality to the swagger spec.
   116  
   117  For generating a swagger specification document this toolkit supports:
   118  
   119  Vendor extension | Description
   120  -----------------|-------------
   121  `x-isnullable`   | makes a property value nullable, for go code that means a pointer
   122  `x-nullable`     | makes a property value nullable, for go code that means a pointer
   123  `x-go-name`      | the go name of a type
   124  `x-go-package`   | the go package of a type
   125  `x-class`        | this is used in conjunction with discriminators to give a full type name
   126  `x-omitempty`    | this is used to control presence of omitempty tag to be used by JSON Marshaler. if the field is required, this extension doesn't take effect
   127  `x-go-enum-ci`   | make a string enumeration case-insensitive