github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/generator/templates/markdown/docs.gotmpl (about) 1 {{- define "externalDoc" }}{{/* renders external documentation */}} 2 {{- with .ExternalDocs }} 3 {{- if .URL }} 4 {{- if .Description }} 5 > [{{ mdBlock .Description }}]({{ .URL }}) 6 {{- else }} 7 > [Read more]({{ .URL }}) 8 {{- end }} 9 {{- else }} 10 > {{ mdBlock .Description }} 11 {{- end }} 12 {{- end }} 13 {{- end }} 14 15 {{- define "docParam" }}{{/* renders a parameter with simple schema */}} 16 | {{ .Name }} | `{{ .Location }}` | {{ paramDocType . }} | `{{ .GoType }}` | {{ if .CollectionFormat }}`{{ docCollectionFormat .CollectionFormat .Child }}`{{ end }} | {{ if .Required }}✓{{ end }} | {{ if .Default }}`{{ json .Default }}`{{ end }} | {{ mdBlock .Description }} | 17 {{- end }} 18 19 {{- define "docModelSchema" }}{{/* renders a schema */}} 20 {{- if .IsArray }} 21 {{- if .IsAliased }} 22 [{{- dropPackage .GoType }}](#{{ dasherize (dropPackage .GoType) -}}) 23 {{- else if .Items }} 24 {{- if and .Items.IsPrimitive (not .Items.IsAliased) -}} 25 {{- schemaDocType . -}} 26 {{- else -}} 27 [][{{- dropPackage .Items.GoType }}](#{{ dasherize (dropPackage .Items.GoType) -}}) 28 {{- end -}} 29 {{- else -}} 30 []any{{ printf " " -}} 31 {{- end -}} 32 {{- else if and .IsMap (not .IsAdditionalProperties) -}} 33 {{- if .IsAliased -}} 34 [{{- dropPackage .GoType }}](#{{ dasherize (dropPackage .GoType) -}}) 35 {{- else if .ElemType }} 36 {{- if and .ElemType.IsPrimitive (not .ElemType.IsAliased) (not .ElemType.IsInterface) -}} 37 {{ schemaDocMapType . -}} 38 {{- else if .ElemType.IsInterface -}} 39 map of any{{ printf " " -}} 40 {{- else -}} 41 map of [{{- dropPackage .ElemType.GoType }}](#{{ dasherize (dropPackage .ElemType.GoType) -}}) 42 {{- end -}} 43 {{- else -}} 44 map of any{{ printf " " -}} 45 {{- end -}} 46 {{- else if and .IsAliased .IsPrimitive (not .IsSuperAlias) -}} 47 | Name | Type | Go type | Default | Description | Example | 48 |------|------|---------| ------- |-------------|---------| 49 | {{ .Name }} | {{ schemaDocType . }}| {{ .AliasedType }} | {{ if .Default }}`{{ json .Default }}`{{ end }}| {{ mdBlock .Description }} | {{ if .Example }}`{{ .Example }}`{{ end }} | 50 {{ printf "\n" }} 51 {{- else if or (and .IsAliased (not (.IsAdditionalProperties))) (and .IsComplexObject (not .Properties) (not .AllOf)) -}} 52 [{{- dropPackage .GoType }}](#{{ dasherize (dropPackage .GoType) -}}) 53 {{- else if and .IsInterface (not .IsAliased) (not .IsMap) -}} 54 any 55 {{- else -}} 56 {{- range .AllOf }} 57 {{- if .IsAnonymous }} 58 * inlined member (*{{ .Name }}*) 59 60 {{ template "docModelSchema" . }} 61 {{- else if or .IsComplexObject .IsPrimitive }} 62 * composed type [{{- dropPackage .GoType }}](#{{ dasherize (dropPackage .GoType) -}}) 63 {{- else }} 64 * {{ template "docModelSchema" . }} 65 {{- end }} 66 {{- end }} 67 {{- if .Properties }} 68 69 **{{ if .IsTuple }}Tuple members{{ else }}Properties{{ end }}** 70 71 | Name | Type | Go type | Required | Default | Description | Example | 72 |------|------|---------|:--------:| ------- |-------------|---------| 73 {{- range .Properties }} 74 | {{ .Name }} | {{ template "docSchemaSimple" . }}| `{{ .GoType }}` | {{ if .Required }}✓{{ end }} | {{ if .Default }}`{{ json .Default }}`{{ end }}| {{ mdBlock .Description }} | {{ if .Example }}`{{ .Example }}`{{ end }} | 75 {{- end }} 76 {{ printf "\n" }} 77 {{- end }} 78 {{- if .HasAdditionalProperties }} 79 80 **Additional Properties** 81 {{- with .AdditionalProperties }} 82 {{- if .IsInterface }} 83 84 any 85 {{- else if .IsPrimitive }} 86 87 | Type | Go type | Default | Description | Example | 88 |------|---------| ------- |-------------|---------| 89 | {{ template "docSchemaSimple" . }} | `{{ .GoType }}` |{{ if .Default }}`{{ json .Default }}`{{ end }}| {{ mdBlock .Description }} | {{ if .Example }}`{{ .Example }}`{{ end }} | 90 {{- else }} 91 92 {{ template "docModelSchema" . }} 93 {{- end }} 94 {{- end }} 95 {{- end }} 96 {{- if and .IsTuple .HasAdditionalItems }} 97 {{- with .AdditionalItems }} 98 99 **Additional Items** 100 {{- if .IsInterface }} 101 102 any 103 {{- else if .IsPrimitive }} 104 105 | Type | Go type | Default | Description | Example | 106 |------|---------| ------- |-------------|---------| 107 | {{ template "docSchemaSimple" . }} | `{{ .GoType }}` |{{ if .Default }}`{{ json .Default }}`{{ end }}| {{ mdBlock .Description }} | {{ if .Example }}`{{ .Example }}`{{ end }} | 108 {{- else }} 109 110 {{ template "docModelSchema" . }} 111 {{- end }} 112 {{- end }} 113 {{- end }} 114 {{- end -}} 115 {{- end }} 116 117 {{- define "docModel" }}{{/* renders a definition */}} 118 {{- with .Description }} 119 > {{ .}} 120 {{- end }} 121 {{- if .ExternalDocs }} 122 {{ template "externalDoc" . }} 123 {{- end }} 124 {{ if or .Description .ExternalDocs }} 125 {{ printf "\n" }} 126 {{- end }} 127 128 {{ template "docModelSchema" .}} 129 {{- end }} 130 131 {{- define "docSchemaSimple" }}{{/* renders a simple property */}} 132 {{- if .IsAliased -}} 133 [{{- dropPackage .GoType }}](#{{ dasherize (dropPackage .GoType) -}}) 134 {{- else if .IsArray }} 135 {{- if .Items }} 136 {{- if and .Items.IsPrimitive (not .Items.IsAliased) -}} 137 {{- schemaDocType . -}} 138 {{- else -}} 139 [][{{- dropPackage .Items.GoType }}](#{{ dasherize (dropPackage .Items.GoType) -}}) 140 {{- end -}} 141 {{- else -}} 142 []any{{ printf " " -}} 143 {{- end -}} 144 {{- else if .IsMap -}} 145 {{- if .ElemType }} 146 {{- if and .ElemType.IsPrimitive (not .ElemType.IsAliased) (not .ElemType.IsInterface) -}} 147 {{ schemaDocMapType . -}} 148 {{- else if .ElemType.IsInterface -}} 149 map of any{{ printf " " -}} 150 {{- else -}} 151 map of [{{- dropPackage .ElemType.GoType }}](#{{ dasherize (dropPackage .ElemType.GoType) -}}) 152 {{- end -}} 153 {{- else -}} 154 map of any{{ printf " " -}} 155 {{- end -}} 156 {{- else if .IsPrimitive -}} 157 {{- schemaDocType . -}} 158 {{- else -}} 159 [{{- dropPackage .GoType }}](#{{ dasherize (dropPackage .GoType) -}}) 160 {{- end -}} 161 {{- end }} 162 163 {{- define "docModelBodyParam" }}{{/* layout for body param schema */}} 164 | {{ .Name }} | `body` | {{ template "docSchemaSimple" .Schema }} | `{{ .Schema.GoType }}` | | {{ if .Required }}✓{{ end }} | {{ if .Default }}`{{ json .Default }}`{{ end }}| {{ mdBlock .Description }} | 165 {{- end }} 166 167 {{- define "docHeaders" }}{{/* renders response headers */}} 168 {{- if .Headers }} 169 | Name | Type | Go type | Separator | Default | Description | 170 |------|------|---------|-----------|---------|-------------| 171 {{- range .Headers }} 172 | {{ .Name }} | {{ headerDocType . }} | `{{ .GoType }}` | {{ if .CollectionFormat }}`{{ docCollectionFormat .CollectionFormat .Child }}`{{ end }} | {{ if .Default }}`{{ json .Default }}`{{ end }} | {{ mdBlock .Description }} | 173 {{- end }} 174 {{- end }} 175 {{- end }} 176 177 {{/* spec top-level information block */}} 178 {{- if .Info }} 179 {{- with .Info.Title }} 180 # {{ . }} 181 {{- end }} 182 183 {{- with .Info.Description }} 184 {{ . }} 185 {{- end }} 186 {{ template "externalDoc" . }} 187 188 {{- if or .Info.Version .Info.License .Info.Contact .Info.TermsOfService }} 189 190 ## Informations 191 {{- end }} 192 193 {{- with .Info.Version }} 194 195 ### Version 196 197 {{ . }} 198 {{- end }} 199 200 {{- with .Info.License }} 201 202 ### License 203 204 {{ if .Name }}[{{ .Name }}]({{ end}}{{ .URL }}{{ if .Name }}){{ end }} 205 {{- end }} 206 207 {{- with .Info.Contact }} 208 209 ### Contact 210 211 {{ .Name }} {{ .Email }} {{ .URL }} 212 {{- end }} 213 214 {{- with .Info.TermsOfService }} 215 216 ### Terms Of Service 217 218 {{ . }} 219 {{- end }} 220 {{- else }} 221 {{ template "externalDoc" . }} 222 {{- end }} 223 224 {{- if .Tags }} 225 226 ## Tags 227 {{- range .Tags }} 228 229 ### <span id="tag-{{ dasherize .Name }}"></span>{{ if .ExternalDocs }}[{{ .Name }}]({{ .ExternalDocs.URL }}{{ if .ExternalDocs.Description }} {{ printf "%q" .ExternalDocs.Description }}{{ end }}){{ else }}{{ .Name }}{{ end }} 230 {{- if .Description }} 231 232 {{ .Description }} 233 {{- end }} 234 {{- end }} 235 {{- end }} 236 237 {{- if or .Schemes .Consumes .Produces }} 238 239 ## Content negotiation 240 {{- end }} 241 {{- if .Schemes }} 242 243 ### URI Schemes 244 {{- range .Schemes }} 245 * {{ . }} 246 {{- end }} 247 {{- range .ExtraSchemes }} 248 * {{ . }} 249 {{- end }} 250 {{- end }} 251 252 {{- if .Consumes }} 253 254 ### Consumes 255 {{- range .Consumes }} 256 {{- range .AllSerializers }} 257 * {{ .MediaType }} 258 {{- end }} 259 {{- end }} 260 {{- end }}{{/* end .Schemes */}} 261 262 {{- if .Produces }} 263 264 ### Produces 265 {{- range .Produces }} 266 {{- range .AllSerializers }} 267 * {{ .MediaType }} 268 {{- end }} 269 {{- end }} 270 {{- end }} 271 272 {{- if or .SecurityDefinitions .SecurityRequirements }} 273 274 ## Access control 275 {{- end }} 276 {{- if .SecurityDefinitions }} 277 278 ### Security Schemes 279 {{- range .SecurityDefinitions }} 280 281 #### {{ .ID }}{{ if .Source }} ({{ .Source }}{{ with .Name }}: {{ . }}{{ end }}){{ end }} 282 283 {{ .Description }} 284 285 {{- with .Type }} 286 287 > **Type**: {{ . }} 288 {{- end }} 289 {{- if .IsOAuth2}} 290 {{- with .Flow }} 291 > 292 > **Flow**: {{ . }} 293 {{- end }} 294 {{- with .AuthorizationURL }} 295 > 296 > **Authorization URL**: {{ . }} 297 {{- end }} 298 {{- with .TokenURL }} 299 > 300 > **Token URL**: {{ . }} 301 {{- end }} 302 {{ if .ScopesDesc }} 303 304 ##### Scopes 305 306 Name | Description 307 -----|------------- 308 {{- range .ScopesDesc }} 309 {{ .Name }} | {{ .Description }} 310 {{- end }} 311 {{- end }} 312 {{- end }} 313 {{- end }} 314 {{- end }}{{/* end .SecurityDefinitions */}} 315 316 {{- if .SecurityRequirements }} 317 318 ### Security Requirements 319 320 {{- range .SecurityRequirements }} 321 * {{ .Name }}{{ if .Scopes }}: {{ range $idx, $scope := .Scopes }}{{ if gt $idx 0 }}, {{ end }}{{ $scope }}{{ end }} 322 {{- end }} 323 {{- end }} 324 {{- end }}{{/* end .SecurityRequirements */}} 325 326 ## All endpoints{{/* an index of all API endpoints */}} 327 328 {{- $alltags := .Tags }} 329 {{- range .OperationGroups }} 330 331 ### {{ .PackageAlias }} 332 {{- $pkg := .PackageAlias }} 333 {{- range $alltags }} 334 {{- if eq .Name $pkg }} 335 336 {{ template "externalDoc" . }} 337 {{- end }} 338 {{- end }} 339 340 | Method | URI | Name | Summary | 341 |---------|---------|--------|---------| 342 {{- range .Operations }} 343 | {{ upper .Method }} | {{ joinPath .BasePath .Path }} | [{{ humanize .Name }}](#{{ dasherize .Name }}) | {{ .Summary }} | 344 {{- end }} 345 {{ printf "\n" }} 346 {{- end }} 347 348 ## Paths{{/* all paths to operations */}} 349 350 {{- range .Operations }} 351 {{- $opname := .Name }} 352 353 ### <span id="{{ dasherize .Name }}"></span> {{ if .Summary }}{{ mdBlock .Summary }}{{ else }}{{ humanize .Name }}{{ end }} (*{{ .Name }}*) 354 355 ``` 356 {{ upper .Method }} {{ joinPath .BasePath .Path }} 357 ``` 358 {{- with .Description }} 359 360 {{ . }} 361 {{- end }} 362 363 {{- with .ExternalDocs }} 364 365 > {{ if .URL }}[Read more]({{ .URL }} "{{ .Description }}"){{ end }} 366 {{- end }} 367 368 {{- if or (gt (len .SchemeOverrides) 0) (gt (len .ExtraSchemeOverrides) 0) }} 369 370 #### URI Schemes 371 372 {{- range .SchemeOverrides }} 373 * {{ . }} 374 {{- end }} 375 {{- range .ExtraSchemeOverrides }} 376 * {{ . }} 377 {{- end }} 378 {{- end }} 379 380 {{- if .Consumes }} 381 382 #### Consumes 383 384 {{- range .Consumes }} 385 * {{ . }} 386 {{- end }} 387 {{- end }} 388 389 {{- if .Produces }} 390 391 #### Produces 392 393 {{- range .Produces }} 394 * {{ . }} 395 {{- end }} 396 {{- end }} 397 398 {{- if .SecurityRequirements }} 399 400 #### Security Requirements 401 {{- range .SecurityRequirements }} 402 * {{ .Name }}{{ if .Scopes }}: {{ range $idx, $scope := .Scopes }}{{ if gt $idx 0 }}, {{ end }}{{ $scope }}{{ end }}{{ end }} 403 {{- end }} 404 {{- end }} 405 406 {{- if .Params }} 407 408 #### Parameters 409 410 | Name | Source | Type | Go type | Separator | Required | Default | Description | 411 |------|--------|------|---------|-----------| :------: |---------|-------------| 412 {{- range .PathParams }}{{ template "docParam" . }}{{ end }} 413 {{- range .HeaderParams }}{{ template "docParam" . }}{{ end }} 414 {{- range .QueryParams }}{{ template "docParam" . }}{{ end }} 415 {{- range .FormParams }}{{ template "docParam" . }}{{ end }} 416 {{- range .Params }} 417 {{- if .IsBodyParam }} 418 {{- template "docModelBodyParam" . }} 419 {{- end }} 420 {{- end }} 421 {{- end }}{{/* end .Params */}} 422 423 #### All responses 424 | Code | Status | Description | Has headers | Schema | 425 |------|--------|-------------|:-----------:|--------| 426 {{- range .Responses }} 427 | [{{.Code}}](#{{ dasherize $opname }}-{{ .Code }}) | {{ httpStatus .Code }} | {{ mdBlock .Description }} | {{ if .Headers }}✓{{ end }} | [schema](#{{ dasherize $opname }}-{{ .Code }}-schema) | 428 {{- end }} 429 {{- with .DefaultResponse }} 430 | [default](#{{ dasherize $opname }}-default) | | {{ mdBlock .Description }} | {{ if .Headers }}✓{{ end }} | [schema](#{{ dasherize $opname }}-default-schema) | 431 {{- end }} 432 433 #### Responses 434 {{ range .Responses }} 435 436 ##### <span id="{{ dasherize $opname }}-{{ .Code }}"></span> {{.Code}}{{ if .Description }} - {{ mdBlock .Description }}{{ end }} 437 Status: {{ httpStatus .Code }} 438 439 ###### <span id="{{ dasherize $opname }}-{{ .Code }}-schema"></span> Schema 440 {{- if .Schema }} 441 {{ template "docModel" .Schema }} 442 {{- end }} 443 444 {{- if .Examples }} 445 446 ###### Examples 447 {{ range .Examples }} 448 **{{ .MediaType }}** 449 ```json 450 {{ prettyjson .Example }} 451 ``` 452 {{- end }} 453 {{- end }} 454 455 {{- if .Headers }} 456 457 ###### Response headers 458 {{ template "docHeaders" . }} 459 {{- end }} 460 {{- end }} 461 462 {{- with .DefaultResponse }} 463 464 ##### <span id="{{ dasherize $opname }}-default"></span> Default Response 465 {{ mdBlock .Description }} 466 467 ###### <span id="{{ dasherize $opname }}-default-schema"></span> Schema 468 {{- if .Schema }} 469 {{ template "docModel" .Schema }} 470 {{- else }} 471 empty schema 472 {{- end }} 473 474 {{- if .Examples }} 475 476 ###### Examples 477 {{ range .Examples }} 478 **{{ .MediaType }}** 479 ```json 480 {{ .Example }} 481 ``` 482 {{- end }} 483 {{- end }} 484 485 {{- if .Headers }} 486 487 ###### Response headers 488 {{ template "docHeaders" . }} 489 {{- end }} 490 {{- end }} 491 492 {{- if .ExtraSchemas }} 493 494 ###### Inlined models 495 {{- range .ExtraSchemas }} 496 {{- if ne .Name "" }} 497 498 **<span id="{{ dasherize .Name }}"></span> {{ .Name }}** 499 500 {{ template "docModel" . }} 501 {{- end }} 502 {{- end }} 503 {{- end }} 504 505 {{- end }}{{/* end .Operations */}} 506 507 ## Models 508 509 {{- range .Models }} 510 511 ### <span id="{{ dasherize .Name }}"></span> {{ .Name }} 512 513 {{ template "docModel" . }} 514 515 {{- if .ExtraSchemas }} 516 517 #### Inlined models 518 {{- range .ExtraSchemas }} 519 {{- if ne .Name "" }} 520 521 **<span id="{{ dasherize .Name }}"></span> {{ .Name }}** 522 523 {{ template "docModel" . }} 524 {{- end }} 525 {{- end }} 526 {{- end }} 527 {{- end }}