parvez3019 / go-swagger3 Goto Github PK

Currently there are no pipelines (GitHub actions) when a pull request is open. It would be great to add a pipeline of linting and another that runs the tests

In Param config, if we pass {in} as query, path, it won't generate Request Param Config in oas.yml.
It also doesn't have {required} information in the oas.yml.
Does someone know how to generate it or it's a bug?

@parvez3019 when custom type objects are generated in Components two exact equal objects are generated,one with the name of the custom type alone and another with the name plus the package.

e.g. in the integration_test's expected.json there is a CreateUserRequest (among other custom types) which appears twice in Components; CreateUserRequest and github.com.parvez3019.go-swagger3.model.CreateUserRequest. The $Ref points to github.com.parvez3019.go-swagger3.model.CreateUserRequest and the other is never used.

Why is this? Shouldn't there be only one of the the objects?

https://go.dev/doc/go-get-install-deprecation go get command is deprecated in new versions of go

Hi,

I am working with a codebase that has has the following type to record the status of operations on key resources.

type apiModifyKeySuccess struct {
	Key     string `json:"key" example:"12345678987654321"`
	Status  string `json:"status"` example:"ok"`
	Action  string `json:"action"` example:"added"`
	KeyHash string `json:"key_hash,omitempty"` example:"bc123456"
}

The Action field can accept values added, deleted or modified

I have used the example tag to give example values for the response in the OAS generated documentation. However, this example is generated globally across all endpoints.

For example, endpoint paths for adding and deleting a key render the same example response with Action example value being displayed as "added".

Is it possible to use the @success tag to override the example for the type?

// @Title Create a key.
// @Description Create a new key and return associated details in response.
// @Param   key  body  user.SessionState  true  "Info for key relating to access rights, policies etc."
// @Success  201  object  apiModifyKeySuccess  "JSON response containing the new key and hash
// @Resource keys
// @Route /api/keys [post]
func AddKey() {
  // ...
}

// @Title Delete a key.
// @Description Delete a given key.
// @Param  keyID  path  string  true  "Id of a specific key."
// @Success  200  object  apiModifyKeySuccess   "Returns details of the key and confirmation of deletion action"
// @Resource keys
// @Route /api/keys [delete]
func DeleteKey() {
  // ...
}

Hello,

This is my first time using this project. Previously, I used go-swagger, but now I prefer to use OpenAPI 3.0.

After studying the README, I'm not sure if generic classes are supported. Could you please confirm whether this project can handle generic types in Swagger?

Thank you for your assistance.

What I mean is that when generating the swagger yaml file normally it follows the next structure provided by Swagger Editor, you can follow the Load PetStore OAS 3.0 example:

• openapi: 3.0.0
• info
• externalDocs
• servers
• tags
• path
• components

The structure that I obtained when generating the yaml file follows:

• components
• info
• openapi: 3.0.0
• path
• servers

It will be helpful to update it as the Swagger Editor suggests.

If you have an alias like below:

type APIResponse = ApiError

type ApiError struct {
	Status  string
	Message string
	Meta    interface{}
	ID      string `json:",omitempty"`
}

The schema created is wrong. It produces

components:
  schemas:
    APIResponse:
      type: ApiError

Currently there are only integration tests. To ensure a more robust and reliable codebase, it's needed to expand our test suite to include unit tests.

I like this library but why is GPL 3.0 necessary? Isn’t it virtually useless for serious usage this way?

type Response struct {
field1 *string json:"field1,omitempty"
field2 *string json:"field2,omitempty"
}

I want to indicate that the response will either contain field1 or field2

Sample spec:

    Response:
      oneOf:
        - $ref: '#/components/schemas/Response1'
        - $ref: '#/components/schemas/Response2'

Hi,

I am trying to learn go-swagger3 and so far have managed to get a working demo setup. I am now trying it on a larger codebase which contains a fork to an external repository. Subsequently, the go.mod file uses the replace directive, e.g. something similar to:

g.mod file

// last line of go.mod file uses replace directive for fork of external module
replace example.io/goexample => github.com/example.org/goexample v1.20.7

When I issue the command from the project root folder:

go-swagger3 --debug --module-path . --output oas.yml --schema-without-pkg --generate-yaml true

Parsing of the go.mod fails with error:

INFO[0000] Parsing Initialized
INFO[0000] Parsing Info ...
INFO[0000] Parsing Modules ...
INFO[0000] Parsing GoMod Info ...
2023/04/28 15:51:48 Error: expect package version, got "=>"

If I remove the replace directive in the go.mod file the oas.yml file is generated successfully by go-swagger3.

Will there be future support for parsing the replace directive for projects that use forks of external modules?

This is what swaggo can do：

// JSONResult's data field will be overridden by the specific type proto.Order
@success 200 {object} ReturnValue {data=proto.Order} "desc"

then custom struce can as a common response type like :

type ReturnValue struct {
	Data   interface{} `json:"data"`
	Status uint        `json:"status" example:"0"`
	Msg    string      `json:"msg" example:"成功"`
}

when I use struct ReturnValue as success response , I can put the truely model in data field.
Does this lib support this? I didn`t found it in docs.

I want to add some restrictions to my fields in responses and parameters such as min length, max length and type. How can I do this or it doesn't implemented now? I don't find anything about it in readme.

Example of JSON of OpenAPI specification for response.

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer"
      },
    "title": {
      "type": "string",
      "maxLength": 50
    }
  }
}

Example of JSON of OpenAPI specification for parameter.

{
   "name": "username",
   "in": "path",
   "description": "username to fetch",
   "required": true,
   "schema": {
     "type": "string",
     "maxLength": 100
   }
}

1. How should I comment the file and text in form?
2. If file is used instead of body, the parameter must not contain underscores, such as file_name.

Why not contain a swagger ui in this?
I don`t know how to preview the doc in my project……

the source code looks very similar

Hi, Is there any way to add these https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html extensions to the source code, so that generated API spec will have these extensions

Please add an option to add operationId as well.

I would like to mark Name as nullable field. How can I achieve that?

type Task struct {
	ID        int            `json:"task_id" gorm:"index:idx_name,unique" required:"true"`
	Name      string         `json:"task_name"  required:"true"`
}

I've tried nullable: true, x-nullable: true without much success. Returned json doesn't return anything that would resemble nullability.

We have query params formatted like this:

// @param filter.id
// @param filter.locationId

and it cuts prefix part and only accepts everything after dot:

Swagger:

Openapi.json:
...

paths:
  /assortment/planogram:
    get:
      description: ' Returns planogram based on query params.'
      parameters:
      - description: Use as filter.id! Planogram dbKey [comma separated list]
        in: query
        name: id
        required: true
        schema:
          description: Use as filter.id! Planogram dbKey [comma separated list]
          format: string
          type: string
      - description: Use as filter.locationId! Location ID
        in: query
        name: locationId
        required: true
        schema:
          description: Use as filter.locationId! Location ID
          format: string
          type: string

Is there any way to use params with dot?

Thanks.

Potential fix that works:
Within parser/operations/param.go, update regular expression to this one to support dot as well:

re := regexp.MustCompile(`([-.\w]+)[\s]+([\w]+)[\s]+([\w./\[\]]+)[\s]+([\w]+)[\s]+"([^"]+)"`)

go-swagger3: command not found
After installation via go get and execution of go-swagger3 --module-path . --main-file-path ./cmd/main/main.go --output oas.json

Hi,

How is it possible to document a 204 status no content response using @success, e.g // @Success 204 object nil "No response"?

Is this functionality possible?

Hi, I realized that go-swagger3 still continues with the type mapping for those fields marked with skip: "true".
For example:

type Foo struct {
  field1 string `json:"field1"`
  field2 string `json:"field2"`
  field3 Bar `json:"field3" skip:"true"`
}

type Bar struct {
  ...
}

And, if I don't want to map the Bar type, it also processes it.

I get the following when trying to add basic security onto my endpoints. Are you able to see why? Looking at the readme and examples i've done the same thing.

PS G:\gok8> go-swagger3 --module-path . --output .\swaggerui\swagger.yml --schema-without-pkg --generate-yaml true
time="2022-06-05T15:01:31+01:00" level=info msg="Parsing Initialized"
time="2022-06-05T15:01:31+01:00" level=info msg="Parsing Info ..."
time="2022-06-05T15:01:31+01:00" level=info msg="Parsing Modules ..."
time="2022-06-05T15:01:31+01:00" level=info msg="Parsing GoMod Info ..."
time="2022-06-05T15:01:32+01:00" level=info msg="Parsing APIs ..."
2022/06/05 15:01:35 Error: NilSchemaProperties : parseHeaders can not parse Header schema model.Headers

Model file:

package model

// Headers represents the model for header params
// @HeaderParameters Headers
type Headers struct {
	Authorization string `parse:"Authorization" json:"Authorization" example:"Bearer thisisatest" skip:"true"`
}

Handler file:

package handler

// @Tag namespace
// @Title List namespaces
// @Description Get a list of namespaces.
// @Header model.Headers
// @Param request body model.namespaceQuery true "The query to filter namespaces"
// @Success 200 {object} model.namespaceResponse "The response from the kubernetes cluster"
// @Router /namespace [get]
func listNamespaces() {
	return
}

If you have a struct that has map with struct values, the swagger generated does not reference the AccessDefinition.

type Policys struct {	
AccessRights                  map[string]AccessDefinitions      `bson:"access_rights" json:"access_rights"`
}

type AccessDefinitions struct {
	Name string `json:"name"`
}

This is what is produced instead of using ref to reference the already created AccessDefinitions :

  schemas:
    AccessDefinitions:
      properties:
        name:
          type: string
      type: object
    Policys:
      properties:
        access_rights:
          properties:
            key:
              properties:
                name:
                  type: string
              type: object
          type: object
      type: object ```

When using go-swagger with the flag --generate-yaml and no --output set like oas.yml the file generated is oas.json but inside has the yaml syntax

Is there any docker image available?

Hi, I can't find an example of error response in documentation, so I'm wondering does it also support errors, because it fails on the bellow example.

Example:

package pog

// @title Get Planograms.
// @description Returns planogram based on query params.
// @param id query string true "Use as filter.id! Planogram dbKey [comma separated list]"
// @param locationId query string true "Use as filter.locationId! Location ID"
// @param include query string false "Includes. Can be: position, fixture, liveFlrFixture"
// @param commodity query string false "Use as filter.commodity! Commodity"
// @param commodityGroup query string false "Use as filter.commodityGroup! Commodity Group"
// @param isDigitalScreen query string false "Use as filter.isDigitalScreen! IsDigitalScreen. Can be: true, false"
// @success 200 {object} GetPogsResponse
// @failure 400 {object} types.ValidationError
// @failure 404 {object} types.ErrResponse
// @failure 500 {object} types.ErrResponse
// @route assortment/planogram [get]
func (h *Handler) GetPogs(ctx *krogo.Context) (interface{}, error) { ....

package types

type ValidationError struct {
StatusCode int json:"statusCode" xml:"statusCode"
Errors []error json:"errors" xml:"errors"
}

Error:
FATA[0014] Can not find definition of error ast.TypeSpec. Current package types

Update:
It works with such trick, if instead of []error just use new typetype errors []error. But of course this is not the greatest solution, I guess there should be simple way to use []error

type errors []error

// swagger:model ValidationErrorResponse
type ValidationErrorResponse struct {
StatusCode int json:"statusCode" xml:"statusCode"
Errors errors json:"errors" xml:"errors"
}

//main.go

// @Title test
// @Version 0.0.0
package main

type A struct {
	A string `json:"a" required:""`
}
type B struct {
	A
	B string `json:"bb" required:""`
}

// @Title test
// @Param  in body  B  true  "x"
// @Route  / [GET]
func main() {

}

//swagger.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "test",
    "version": "0.0.0"
  },
  "servers": [
    {
      "url": "/",
      "description": "Default Server URL"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "responses": {},
        "summary": "test",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/B"
              }
            }
          },
          "required": true
        }
      }
    }
  },
  "components": {
    "schemas": {
      "A": {
        "type": "object",
        "required": [
          "a"
        ],
        "properties": {
          "a": {
            "type": "string"
          }
        }
      },
      "B": {
        "type": "object",
        "required": [
          "bb"
        ],
        "properties": {
          "bb": {
            "type": "string"
          },
          "a": {
            "type": "string"
          }
        }
      }
    }
  }
}

how to write let type B required is ["a","bb"]