I am trying to use generate swagger spec from my API handler.
I have installed the go-swagger from go get:
go get -u github.com/go-swagger/go-swagger/cmd/swagger
See the project structure below:
main.go uses handler definitions in products.go. (API works and is tested)
Swagger spec in product.go:
// Package classification of Product API.
//
// Documenting for Product API
//
//
//
// Schemes: http, https
// BasePath: /
// Version: 0.0.1
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// swagger:meta
Running the following command from main.go path:
GO111MODULE=off swagger generate spec -o ./swagger.yaml --scan-models
Response:
info: {}
paths: {}
swagger: "2.0"
Expected Response:
basePath: /
consumes:
- application/json
info:
description: Documenting for Product API
title:
version: 0.0.1
paths: {}
producrs:
- application/json
schemes:
- http
swagger: "2.0"
I assume you are following Nic's MSA Go tutorial.
In case you haven't figure out the issue yet, you forgot to add a space for the contents. (lines between the first and last line)
Your documentation comment should be as below
// Documentation for Product API
//
// Schemes: http
// BasePath: /
// Version: 1.0.0
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// swagger:meta
In adition to #sssang comment. Make sure you leave no space between Documentation comment and the package definition.
// Documentation for Product API
//
// Schemes: http
// BasePath: /
// Version: 1.0.0
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// swagger:meta
package handlers
[...rest of your code]
Related
I am typing to generate in path parameters using go-swagger. But after running swagger generate spec -o ./swagger.yaml --scan-models I see the generated swagger has in:query rather than in:path
package types
package types
type URCapID struct {
Vendor string `yaml:"vendorID" json:"vendorID" mapstructure:"vendorID"`
ID string `yaml:"urcapID" json:"urcapID" mapstructure:"urcapID"`
Version string `yaml:"version" json:"version" mapstructure:"version"`
}
Handle function
// swagger:parameters deleteURCap
type urcapIDParam struct {
// The id of the urcap to uninstall/delete
// in: path
// required: true
types.URCapID
}
// Uninstall and deletes urcap if installed
func Uninstall(w http.ResponseWriter, r *http.Request) {
// swagger:route DELETE /urcap/{vendorID}/{urcapID}/{version} URCap deleteURCap
//
// Delete/Uninstall URCap if installed.
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Schemes: http
//
// Responses:
// 201: noContent
}
Auto generated swagger.yaml
/urcap/{vendorID}/{urcapID}/{version}:
delete:
consumes:
- application/json
operationId: deleteURCap
parameters:
- in: query
name: vendorID
type: string
x-go-name: Vendor
- in: query
name: urcapID
type: string
x-go-name: ID
- in: query
name: version
type: string
x-go-name: Version
produces:
- application/json
responses:
"201":
$ref: '#/responses/noContent'
schemes:
- http
summary: Delete/Uninstall URCap if installed.
tags:
- URCap
I'm trying to implement go-swagger but this error keep flashing. I'm using windows machine. I appreciate any help.
My implementation:
opts := middleware.RedocOpts{RedocURL: "/swagger.yaml"}
sh := middleware.Redoc(opts, nil)
getRouter.Handle("/docs", sh)
getRouter.Handle("/swagger.yaml", http.FileServer(http.Dir("./")))
My swagger definition:
// Package classification of Product API.
//
// Documentation for Product API
// Schemes: http
// BasePath: /
// version: 1.0.0
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
// swagger:meta
Error message:
The option of Redoc must be
SpecURL
opts := middleware.RedocOpts{SpecURL: "/swagger.yaml"}
instead of RedocURL
opts := middleware.RedocOpts{RedocURL: "/swagger.yaml"}
Cannot understand one thing, why swag init command is generating everything, except SecurityDefinition block
For example, this is my code on main function:
// #title Swagger API
// #version 1.0
// #description This is a documentation for PlatOps Core tool.
// #termsOfService http://platops.com/
// #license.name Apache 2.0
// #license.url http://www.apache.org/licenses/LICENSE-2.0.html
// #host test.com
// #BasePath /v2
// #securityDefinitions.apikey Bearer
// #in header
// #name Authorization
And how I'm using :
// GetUser godoc
// #Summary Retrieves users list
// #Tags users
// #Accept json
// #Produce json
// #Success 200 {object} string
// #Failure 400,404 {object} string
// #Failure 500 {object} string
// #Router /api/users/ [get]
// #Security Bearer
From this, it's generating everything, this path also, but no SecurityDefinition block inside.
I'm trying to implement this one:
https://github.com/swaggo/swag#security
P.S. If I put already generated text on the generated doc file, it's working... so why it cannot generate it?
"securityDefinitions": {
"api_key": {
"type": "apiKey",
"name": "Bearer",
"in": "header"
},
}
Add your security definitions in the file which you are passing in the swag init -g flag... Mostly it should be your main.go file... it should show up once you do that
Looking at the documentation here https://serverless.com/framework/docs/providers/aws/events/apigateway/#custom-response-templates, there doesn't seem to be much detail at all about setting up these templates.
I'm currently looking to remove the default application/json content-type, which is generated during creation of the handler's integration response (pictured below), and replace it with text/html. Is there defined syntax for how to do this hidden somewhere? Or is this level of customization not possible within the current scope of the framework?
Here is my endpoint as defined in serverless.yml
events:
- http:
method: any
path: /
integration: lambda
request:
region: ${env:AwsRegion}
response:
headers:
Content-Type: "'text/html'"
template: $input.path('body')
- http:
method: any
path: /{proxy+}
Which produces the following configuration on AWS Api Gateway:
I did try modifying the specification like this, as a guess, but it threw a syntax error:
template:
text\html: $input.path('body')
Make It Work
It looks like this isn't really supported by the framework, but it can be hacked together by (ab)using statusCodes in your serverless template.
Moving the response template to under a status code, and providing a pattern for that status code, accomplishes what I think you are after. The syntax:
- http:
method: any
path: /
integration: lambda
request:
region: us-east-1
response:
headers:
Content-Type: "'text/html'"
statusCodes:
200:
pattern: ""
template:
text/html: $input.path('body')
Note: Both the pattern and the template must be present.
Is It Really That Bad?
That's up to you, ultimately. I'm calling it a hack because:
It would be much nicer to be able to supply this at the response.template level, rather than at response.statusCodes.200.template.
Specifying one or more statusCodes removes the set of default lambda error regexes that you get when you don't specify any.
It feels like working around the fact that response.template will only accept a string, whereas it could (should?) accept a string or an object (like it does under statusCodes).
Fix It?
The offending code, from /lib/plugins/aws/package/compile/events/apiGateway/lib/method/integration.js:
if (http.response.template) {
_.merge(integrationResponse.ResponseTemplates, {
'application/json': http.response.template,
});
}
if (config.template) {
const template =
typeof config.template === 'string'
? { 'application/json': config.template }
: config.template;
_.merge(integrationResponse.ResponseTemplates, template);
}
I think for this to work under response.template, the code in the first if() would need to behave more like the code in the second if().
Grails is so nice to append the parameters sent to console output in the case of an error:
2011-05-23 12:17:05,173 [http-8080-5] ERROR errors.GrailsExceptionResolver - Exception occurred when processing request: [POST] / - parameters:
maps: on
maps: on
maps: on
maps:
_isPublic:
description: test
name: set1
isPublic: on
Stacktrace follows:
...
But how can I tell it to always show me which parameters are sent (like in Rails, for example)?
My current log4j configuration looks as follows:
error 'org.codehaus.groovy.grails.web.servlet', // controllers
'org.codehaus.groovy.grails.web.pages', // GSP
'org.codehaus.groovy.grails.web.sitemesh', // layouts
'org.codehaus.groovy.grails.web.mapping.filter', // URL mapping
'org.codehaus.groovy.grails.web.mapping', // URL mapping
'org.codehaus.groovy.grails.commons', // core / classloading
'org.codehaus.groovy.grails.plugins', // plugins
'org.codehaus.groovy.grails.orm.hibernate', // hibernate integration
'org.springframework',
'org.hibernate',
'net.sf.ehcache.hibernate'
warn 'org.mortbay.log'
I don't believe Grails itself supports logging the request parameters for each request. However, you can easily implement this yourself in a filter:
package com.example
class MyFilters {
private static final log = org.apache.commons.logging.LogFactory.getLog(this)
def filters = {
paramLogger(controller:'*', action:'*') {
before = {
log.debug "request params: $params"
}
}
}
}
Remember to enable debug logging for this filter in `Config.groovy by adding
debug com.example
to the log4j closure
You probably want to get more output from org.codehaus.groovy.grails.web so set that one to a lower level (debug or trace)