github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/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/thetreep/go-swagger/generator#GenDefinition)
     7    * [Operations](https://godoc.org/github.com/thetreep/go-swagger/generator#GenOperation)
     8    * [Operation groups](https://godoc.org/github.com/thetreep/go-swagger/generator#GenOperationGroup) (tagged groups of operations)
     9    * [Application](https://godoc.org/github.com/thetreep/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  We use the [sprig](https://masterminds.github.io/sprig/) library to provide a large variety of template functions for creating custom templates.
    19  
    20  In addition to this there are a number of added filters you can use inside a template to manipulate values:
    21  
    22  Filter | Description
    23  -------|-------------
    24  pascalize | every word boundary starts with a capital; "some long name" becomes SomeLongName
    25  camelize | every word boundary starts with a capital except the first word; "some long name" becomes someLongName
    26  varname | like camelize, but respects golint naming rules; "some url" becomes someURL
    27  humanize | takes an identifier and adds spaces to it; someLongName becomes "some long name"
    28  snakize | converts to lowercase and separates words with an underscore; someLongName becomes some_long_name
    29  dasherize | convert to lowercase and separates words with a dash; someLongName becomes some-long-name
    30  pluralizeFirstWord | pluralizes the first word of a sentence
    31  json | converts the argument to compact json
    32  prettyjson | converts the argument to pretty-printed json
    33  stripPackage | strips the package name from an identifier
    34  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
    35  joinFilePath | joins the arguments as a file path, cross platform
    36  padSurround | surround an entry with a character n times before and m times after the entry
    37  
    38  ## Template Attributes
    39  
    40  The following modifiers can be applied to a template to modify code-generation behaviour:
    41  
    42  Attribute | Type | Description
    43  ----------|------|-------------
    44  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.
    45  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.
    46  
    47  ## Server generation
    48  
    49  ```
    50  swagger generate server -A TodoList -f ./swagger.json -C default-server.yml
    51  ```
    52  
    53  For the default server generator this config file would have the following content:
    54  
    55  ```yaml
    56  layout:
    57    application:
    58      - name: configure
    59        source: asset:serverConfigureapi
    60        target: "{{ joinFilePath .Target .ServerPackage }}"
    61        file_name: "configure_{{ .Name }}.go"
    62        skip_exists: true
    63      - name: main
    64        source: asset:serverMain
    65        target: "{{ joinFilePath .Target \"cmd\" (dasherize (pascalize .Name)) }}-server"
    66        file_name: "main.go"
    67      - name: embedded_spec
    68        source: asset:swaggerJsonEmbed
    69        target: "{{ joinFilePath .Target .ServerPackage }}"
    70        file_name: "embedded_spec.go"
    71      - name: server
    72        source: asset:serverServer
    73        target: "{{ joinFilePath .Target .ServerPackage }}"
    74        file_name: "server.go"
    75      - name: builder
    76        source: asset:serverBuilder
    77        target: "{{ joinFilePath .Target .ServerPackage .Package }}"
    78        file_name: "{{ snakize (pascalize .Name) }}_api.go"
    79      - name: doc
    80        source: asset:serverDoc
    81        target: "{{ joinFilePath .Target .ServerPackage }}"
    82        file_name: "doc.go"
    83    models:
    84      - name: definition
    85        source: asset:model
    86        target: "{{ joinFilePath .Target .ModelPackage }}"
    87        file_name: "{{ (snakize (pascalize .Name)) }}.go"
    88    operations:
    89      - name: parameters
    90        source: asset:serverParameter
    91        target: "{{ if gt (len .Tags) 0 }}{{ joinFilePath .Target .ServerPackage .APIPackage .Package  }}{{ else }}{{ joinFilePath .Target .ServerPackage .Package  }}{{ end }}"
    92        file_name: "{{ (snakize (pascalize .Name)) }}_parameters.go"
    93      - name: responses
    94        source: asset:serverResponses
    95        target: "{{ if gt (len .Tags) 0 }}{{ joinFilePath .Target .ServerPackage .APIPackage .Package  }}{{ else }}{{ joinFilePath .Target .ServerPackage .Package  }}{{ end }}"
    96        file_name: "{{ (snakize (pascalize .Name)) }}_responses.go"
    97      - name: handler
    98        source: asset:serverOperation
    99        target: "{{ if gt (len .Tags) 0 }}{{ joinFilePath .Target .ServerPackage .APIPackage .Package  }}{{ else }}{{ joinFilePath .Target .ServerPackage .Package  }}{{ end }}"
   100        file_name: "{{ (snakize (pascalize .Name)) }}.go"
   101    operation_groups:
   102  
   103  ```
   104  
   105  ## Client generation
   106  
   107  ```
   108  swagger generate client -A TodoList -f ./swagger.json -C default-client.yml
   109  ```
   110  
   111  For the default client generator this config file would have the following content.
   112  
   113  ```yaml
   114  layout:
   115    application:
   116      - name: facade
   117        source: asset:clientFacade
   118        target: "{{ joinFilePath .Target .ClientPackage }}"
   119        file_name: "{{ .Name }}_client.go"
   120    models:
   121      - name: definition
   122        source: asset:model
   123        target: "{{ joinFilePath .Target .ModelPackage }}"
   124        file_name: "{{ (snakize (pascalize .Name)) }}.go"
   125    operations:
   126      - name: parameters
   127        source: asset:clientParameter
   128        target: "{{ joinFilePath .Target .ClientPackage .Package }}"
   129        file_name: "{{ (snakize (pascalize .Name)) }}_parameters.go"
   130      - name: responses
   131        source: asset:clientResponse
   132        target: "{{ joinFilePath .Target .ClientPackage .Package }}"
   133        file_name: "{{ (snakize (pascalize .Name)) }}_responses.go"
   134    operation_groups:
   135      - name: client
   136        source: asset:clientClient
   137        target: "{{ joinFilePath .Target .ClientPackage .Name }}"
   138        file_name: "{{ (snakize (pascalize .Name)) }}_client.go"
   139  ```