github.com/AngusLu/go-swagger@v0.28.0/docs/use/template_layout.md (about)

     1  # Custom generation
     2  
     3  To completely customize the templates that are being considered, their file names and paths, go-swagger allows you to pass in a configuration file.
     4  There are basically 4 types of items that are being generated:
     5  
     6    * [Models](https://godoc.org/github.com/go-swagger/go-swagger/generator#GenDefinition)
     7    * [Operations](https://godoc.org/github.com/go-swagger/go-swagger/generator#GenOperation)
     8    * [Operation groups](https://godoc.org/github.com/go-swagger/go-swagger/generator#GenOperationGroup) (tagged groups of operations)
     9    * [Application](https://godoc.org/github.com/go-swagger/go-swagger/generator#GenApp)
    10  
    11  You provide a configuration that describes the type of template, the source for where to find the template. For built-in templates the name should be prefixed with `asset:`.
    12  You also provide the target directory and the file name. Directory and file names are processed as templates too and allow for a number of filters.
    13  
    14  We use the viper library to read config values, this means you can provide the configuration file in whichever format you like: json, yaml, hcl or toml.
    15  
    16  ## Available filters in templates
    17  
    18  There are a number of filters you can use inside a template to manipulate values:
    19  
    20  Filter | Description
    21  -------|-------------
    22  pascalize | every word boundary starts with a capital; "some long name" becomes SomeLongName
    23  camelize | every word boundary starts with a capital except the first word; "some long name" becomes someLongName
    24  varname | like camelize, but respects golint naming rules; "some url" becomes someURL
    25  humanize | takes an identifier and adds spaces to it; someLongName becomes "some long name"
    26  snakize | converts to lowercase and separates words with an underscore; someLongName becomes some_long_name
    27  dasherize | convert to lowercase and separates words with a dash; someLongName becomes some-long-name
    28  pluralizeFirstWord | pluralizes the first word of a sentence
    29  json | converts the argument to compact json
    30  prettyjson | converts the argument to pretty-printed json
    31  stripPackage | strips the package name from an identifier
    32  upper | converts the string to upper case
    33  contains | for use in conditions, returns true when the second argument is contained in the first argument, the first argument is a list of strings
    34  joinFilePath | joins the arguments as a file path, cross platform
    35  padSurround | surround an entry with a character n times before and m times after the entry
    36  
    37  ## Template Attributes
    38  
    39  The following modifiers can be applied to a template to modify code-generation behaviour:
    40  
    41  Attribute | Type | Description
    42  ----------|------|-------------
    43  skip_exists|boolean|Skip generating content for a file if the specified target file already exists. Use this for files the user needs to customise.
    44  skip_format|boolean|Skip formatting code from the template according to the standard golang rules. This may be useful if you have your own coding conventions that custom templates already adhere to, or if you are generating non-golang code.
    45  
    46  ## Server generation
    47  
    48  ```
    49  swagger generate server -A TodoList -f ./swagger.json -C default-server.yml
    50  ```
    51  
    52  For the default server generator this config file would have the following content:
    53  
    54  ```yaml
    55  layout:
    56    application:
    57      - name: configure
    58        source: asset:serverConfigureapi
    59        target: "{{ joinFilePath .Target .ServerPackage }}"
    60        file_name: "configure_{{ .Name }}.go"
    61        skip_exists: true
    62      - name: main
    63        source: asset:serverMain
    64        target: "{{ joinFilePath .Target \"cmd\" (dasherize (pascalize .Name)) }}-server"
    65        file_name: "main.go"
    66      - name: embedded_spec
    67        source: asset:swaggerJsonEmbed
    68        target: "{{ joinFilePath .Target .ServerPackage }}"
    69        file_name: "embedded_spec.go"
    70      - name: server
    71        source: asset:serverServer
    72        target: "{{ joinFilePath .Target .ServerPackage }}"
    73        file_name: "server.go"
    74      - name: builder
    75        source: asset:serverBuilder
    76        target: "{{ joinFilePath .Target .ServerPackage .Package }}"
    77        file_name: "{{ snakize (pascalize .Name) }}_api.go"
    78      - name: doc
    79        source: asset:serverDoc
    80        target: "{{ joinFilePath .Target .ServerPackage }}"
    81        file_name: "doc.go"
    82    models:
    83      - name: definition
    84        source: asset:model
    85        target: "{{ joinFilePath .Target .ModelPackage }}"
    86        file_name: "{{ (snakize (pascalize .Name)) }}.go"
    87    operations:
    88      - name: parameters
    89        source: asset:serverParameter
    90        target: "{{ if gt (len .Tags) 0 }}{{ joinFilePath .Target .ServerPackage .APIPackage .Package  }}{{ else }}{{ joinFilePath .Target .ServerPackage .Package  }}{{ end }}"
    91        file_name: "{{ (snakize (pascalize .Name)) }}_parameters.go"
    92      - name: responses
    93        source: asset:serverResponses
    94        target: "{{ if gt (len .Tags) 0 }}{{ joinFilePath .Target .ServerPackage .APIPackage .Package  }}{{ else }}{{ joinFilePath .Target .ServerPackage .Package  }}{{ end }}"
    95        file_name: "{{ (snakize (pascalize .Name)) }}_responses.go"
    96      - name: handler
    97        source: asset:serverOperation
    98        target: "{{ if gt (len .Tags) 0 }}{{ joinFilePath .Target .ServerPackage .APIPackage .Package  }}{{ else }}{{ joinFilePath .Target .ServerPackage .Package  }}{{ end }}"
    99        file_name: "{{ (snakize (pascalize .Name)) }}.go"
   100    operation_groups:
   101  
   102  ```
   103  
   104  ## Client generation
   105  
   106  ```
   107  swagger generate client -A TodoList -f ./swagger.json -C default-client.yml
   108  ```
   109  
   110  For the default client generator this config file would have the following content.
   111  
   112  ```yaml
   113  layout:
   114    application:
   115      - name: facade
   116        source: asset:clientFacade
   117        target: "{{ joinFilePath .Target .ClientPackage }}"
   118        file_name: "{{ .Name }}_client.go"
   119    models:
   120      - name: definition
   121        source: asset:model
   122        target: "{{ joinFilePath .Target .ModelPackage }}"
   123        file_name: "{{ (snakize (pascalize .Name)) }}.go"
   124    operations:
   125      - name: parameters
   126        source: asset:clientParameter
   127        target: "{{ joinFilePath .Target .ClientPackage .Package }}"
   128        file_name: "{{ (snakize (pascalize .Name)) }}_parameters.go"
   129      - name: responses
   130        source: asset:clientResponse
   131        target: "{{ joinFilePath .Target .ClientPackage .Package }}"
   132        file_name: "{{ (snakize (pascalize .Name)) }}_responses.go"
   133    operation_groups:
   134      - name: client
   135        source: asset:clientClient
   136        target: "{{ joinFilePath .Target .ClientPackage .Name }}"
   137        file_name: "{{ (snakize (pascalize .Name)) }}_client.go"
   138  ```