github.com/kaisawind/go-swagger@v0.19.0/docs/faq/faq_swagger.md (about)

     1  <!-- Questions about swagger specs -->
     2  ## Swagger specification
     3  
     4  ### Default vs required
     5  _Use-Case_:  spec validation rejects default object without required properties
     6  
     7  > If we have the default for the firstName and lastName but didn't set the username, which is required,
     8  > we will have an error message showing that we have to put the default for the required field "username" as well.
     9  >
    10  > The "default" section must contain any "required" properties, which is counterintuitive because the "required" properties
    11  > should always be provided explicitly and shouldn’t have defaults.
    12  
    13  Example:
    14  
    15  ```yaml
    16  paths:
    17    /person/{id}:
    18      put:
    19        summary: Put a person
    20        description: Put a person.
    21        consumes:
    22          - application/json
    23        parameters:
    24          - name: id
    25            in: path
    26            description: ID of person
    27            required: true
    28            type: integer
    29          - in: body
    30            name: body
    31            description: Person
    32            schema:
    33              type: object
    34              required:
    35                - username
    36              default:
    37                firstName: John
    38                lastName: Smith
    39              properties:
    40                firstName:
    41                  type: string
    42                lastName:
    43                  type: string
    44                username:
    45                  type: string
    46        responses:
    47          200:
    48            description: successful
    49  ```
    50  
    51  `swagger generate model -f person.yaml`
    52  
    53  I notice that the error message could be prevented if I use `swagger generate model --skip-validation`.
    54  But I think the error message should not show even I just use `swagger generate model -f person.yaml` because
    55  "required" properties should always be provided explicitly and shouldn’t have defaults.
    56  
    57  **Answer:** Those defaults need to be put on the individual members.
    58  
    59  > The default where you put it is a default for the entire object if it is not provided at all.
    60  > Thus it must pass validation of the object schema.
    61  > As per swagger, defaults MUST validate their schema. This differs from json-Schema spec.
    62  
    63  Originally from issue [#1552](https://github.com/go-swagger/go-swagger/issues/1552).
    64  
    65  _Use-Case_: `go-swagger` rejects default object that misses required properties.
    66  
    67  > My understanding is that properties in default and those listed as required are mutually exclusive, because one is supposed
    68  > to explicitly provide required properties, while properties in default can be filled in.
    69  > See https://swagger.io/blog/unlocking-the-spec-the-default-keyword
    70  
    71  Example:
    72  
    73  ```yaml
    74  paths:
    75    /person/{id}:
    76      put:
    77        summary: Put a person
    78        description: Put a person.
    79        consumes:
    80          - application/json
    81        parameters:
    82          - name: id
    83            in: path
    84            description: ID of person
    85            required: true
    86            type: integer
    87          - in: body
    88            name: body
    89            description: Person
    90            schema:
    91              type: object
    92              required:
    93                - username
    94              default:
    95                firstName: John
    96                lastName: Smith
    97              properties:
    98                firstName:
    99                  type: string
   100                lastName:
   101                  type: string
   102                username:
   103                  type: string
   104        responses:
   105          200:
   106            description: successful
   107  ```
   108  
   109  **Answer:** the spec validation warns you about mixing up default with required.
   110  
   111  > If you override this validation (with `swagger generate model --skip-validation`), the model generator would override the
   112  > required clause, and use the default.
   113  
   114  **Would --skip-validation skip any other validations?**
   115  
   116  **Answer:** Yes. `--skip-validation` skips the call to `swagger validate {spec}`, which is normally carried on before generation.
   117  
   118  For some use cases, we have to, since `go-swagger` supports constructs that are not stricly swagger-compliant.
   119  This one is an example: some override silently take place here at generation time.
   120  
   121  Originally from issue [#1501](https://github.com/go-swagger/go-swagger/issues/1501).
   122  
   123  ### type string, format int64 not respected in generator
   124  _Use-Case_:  when generating parameters or models from a swagger file with a definition that specifies type: string and format: int64,
   125   the **generation fails**.
   126  
   127  Example:
   128  
   129  ```json
   130  {
   131      "consumes": [
   132          "application/json"
   133      ],
   134      "definitions": {
   135          "Test": {
   136              "properties": {
   137                  "id": {
   138                      "format": "int64",
   139                      "type": "string"
   140                  }
   141              },
   142              "type": "object"
   143          }
   144      },
   145  ...
   146  ```
   147  
   148  **Answer**: that's an invalid type. The openapi 2.0 spec says the type should be
   149  ```
   150  type: integer
   151  format: int64
   152  ```
   153  
   154  
   155  Originally from issue [#1381](https://github.com/go-swagger/go-swagger/issues/1381).
   156  
   157  ### Duplicate operationId error
   158  _Use-Case_:  my spec indicates duplicate operationIds but for separate endpoints.
   159  When generating a server and there are multiple endpoints, the `operations` directory in `restapi`
   160  contains subdirectories for each of those endpoints.
   161  
   162  Example:
   163  
   164  ```yaml
   165  paths:
   166    '/users/{id}':
   167      parameters:
   168        - name: id
   169          in: path
   170          required: true
   171          type: string
   172      get:
   173        operationId: getById
   174        summary: Get User By ID
   175        tags:
   176          - Users
   177        responses:
   178          '200':
   179            description: ''
   180            schema:
   181              $ref: '#/definitions/user-output'
   182    '/pets/{id}':
   183      parameters:
   184        - name: id
   185          in: path
   186          required: true
   187          type: string
   188      get:
   189        operationId: getById
   190        summary: Get Pet By ID
   191        tags:
   192          - Pets
   193        responses:
   194          '200':
   195            description: ''
   196            schema:
   197              $ref: '#/definitions/pet-output'
   198  ```
   199  
   200  I am expecting a generated structure like so:
   201  ```
   202  └── restapi
   203      ...
   204      ├── operations
   205      │   ├── pets
   206      │   │   ├── ...
   207      │   ├── users
   208      │   │   ├── ...
   209      │   └── ...
   210  ```
   211  
   212  However, instead of generating the server I get this error: `"getById" is defined 2 times`
   213  
   214  Is it possible to bypass this validation error IF the operation ids will go into separate directories?
   215  
   216  **Answer:** operationId is always globally unique per swagger 2.0 specification. The id MUST be unique among all operations described in the API.
   217  
   218  https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject
   219  
   220  > Unique string used to identify the operation. The id MUST be unique among all operations described in the API.
   221  > Tools and libraries MAY use the operationId to uniquely identify an operation,
   222  > therefore, it is recommended to follow common programming naming conventions.
   223  
   224  Originally from issue [#1143](https://github.com/go-swagger/go-swagger/issues/1143).
   225  
   226  -------------------
   227  
   228  Back to [all contributions](README.md#all-contributed-questions)