swagger2markup
swagger2markup copied to clipboard
Swagger2Markup
Query params generates both table and json blob in markdown
Swagger2Markup version: 1.3.1
Given this spec:
swagger: "2.0"
info:
description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters."
version: "1.0.0"
title: "Swagger Petstore"
termsOfService: "http://swagger.io/terms/"
contact:
email: "[email protected]"
license:
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
description: "Everything about your Pets"
externalDocs:
description: "Find out more"
url: "http://swagger.io"
- name: "store"
description: "Access to Petstore orders"
- name: "user"
description: "Operations about user"
externalDocs:
description: "Find out more about our store"
url: "http://swagger.io"
schemes:
- "http"
paths:
/pet/findByStatus:
get:
tags:
- "pet"
summary: "Finds Pets by status"
description: "Multiple status values can be provided with comma separated strings"
operationId: "findPetsByStatus"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "status"
in: "query"
description: "Status values that need to be considered for filter"
required: true
type: "array"
items:
type: "string"
enum:
- "available"
- "pending"
- "sold"
default: "available"
collectionFormat: "multi"
responses:
200:
description: "successful operation"
schema:
type: "array"
items:
$ref: "#/definitions/Pet"
400:
description: "Invalid status value"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
securityDefinitions:
petstore_auth:
type: "oauth2"
authorizationUrl: "http://petstore.swagger.io/oauth/dialog"
flow: "implicit"
scopes:
write:pets: "modify pets in your account"
read:pets: "read your pets"
api_key:
type: "apiKey"
name: "api_key"
in: "header"
definitions:
Category:
type: "object"
properties:
id:
type: "integer"
format: "int64"
name:
type: "string"
xml:
name: "Category"
Tag:
type: "object"
properties:
id:
type: "integer"
format: "int64"
name:
type: "string"
xml:
name: "Tag"
Pet:
type: "object"
required:
- "name"
- "photoUrls"
properties:
id:
type: "integer"
format: "int64"
category:
$ref: "#/definitions/Category"
name:
type: "string"
example: "doggie"
photoUrls:
type: "array"
xml:
name: "photoUrl"
wrapped: true
items:
type: "string"
tags:
type: "array"
xml:
name: "tag"
wrapped: true
items:
$ref: "#/definitions/Tag"
status:
type: "string"
description: "pet status in the store"
enum:
- "available"
- "pending"
- "sold"
xml:
name: "Pet"
You get query params twice:
Here is generated markdown:
<a name="findpetsbystatus"></a>
### Finds Pets by status
\```
GET /pet/findByStatus
\```
#### Description
Multiple status values can be provided with comma separated strings
#### Parameters
|Type|Name|Description|Schema|
|---|---|---|---|
|**Query**|**status** <br>*required*|Status values that need to be considered for filter|< enum<br><br>- available<br>- pending<br>- sold > array(multi)|
#### Responses
|HTTP Code|Description|Schema|
|---|---|---|
|**200**|successful operation|< [Pet](../objects/Pet.md#pet) > array|
|**400**|Invalid status value|No Content|
#### Produces
* `application/xml`
* `application/json`
#### Tags
* pet
#### Example HTTP request
##### Request path
\```
/pet/findByStatus
\```
##### Request query
\```
json :
{
"status" : "string"
}
\```
#### Example HTTP response
##### Response 200
\```
json :
[ {
"id" : 0,
"category" : {
"id" : 0,
"name" : "string"
},
"name" : "doggie",
"photoUrls" : [ "string" ],
"tags" : [ {
"id" : 0,
"name" : "string"
} ],
"status" : "string"
} ]
\```
I don't think the problem is that you get them twice. The first occurrence is the definition and is fine. The second concurrence is a usage example. So that should be there too but as reported in issue #264 the problem with the example is that the format is json instead of having the query parameters in the request string.
Them being optional and in some cases quite numerous, I am not sure I would want them all to always be added to the request path. Specially since there does not seem to be any way to set example values.. just 0s and 'string'
Oh. Someone on my team tried and said query params doesnt support it. I will try again.
On 14 Jul 2017, at 11:14, Robert Winkler [email protected] wrote:
You could set example values in your Swagger Spec.
— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.
The generated examples feature is still somehow incubating. I'm generating examples by using a different tool and include them. For example Spring RestDocs
@RobWin any updates here? Could we possibly get the
``` json :
fixed to
```json
?
I think @cascer1 started working on it, but I don't know when he has time to finish it.
@cascer1 anything I can do to help? btw I think the way code samples get their language on the new line should be a lot quicker and independent fix, can we get that done first maybe?
@cascer1 I have made an effort to fix this myself, but I am not well versed in java and the architecture of this project confuse me. I have "almost" solved it. Here is a patch of where I am at the moment: https://gist.github.com/alkemann/e160861f9a5384c7f0ec7e771da2a0f3
Could you please fork the project and provide a PR? We can review your changes better and add comments.
@alkemann Whoops, I had basically no time these past few months 😮
I'll have a look at the changes very soon!
@alkemann Your PR did help me in getting on the way of resolving that issue. I Added the skipLeadingNewline argument to all block methods so it only gets skipped when a language is present
Don't know if there has been any movement on this one, but I did hack a quick fix that adds required parameters only to the example as an extension to the path element.
