CODEWITHSUNDEEP
openapiswagger-editor
Sammy Cakes
Sammy Cakes

Reputation: 162

How can I include JSON body API examples in Swagger2Markup API requirements (when converting from Swagger YAML)?

I've used the Swagger editor (editor.swagger.io) to create API requirements that look great online in a web browser, but I want to convert this Swagger YAML documentation into a format that can be printed (Word, PDF, Excel, HTML) and read offline.

The only way I've seen to convert the Swagger YAML into a clean, printable API requirements document is using the Swagger2Markup CLI (here's the reference documentation: http://swagger2markup.github.io/swagger2markup/1.3.3/ - Chapter 8 describes the CLI), then converting this adoc format to HTML from AsciiDoctor. The final product is very readable as you can see from the Swagger2Markup reference documentation.

However, unfortunately, the final Swagger2Markup documentation of an API doesn't include JSON or xml examples of the API body, which is arguably the most important part of the documentation in my opinion! For example, in the Swagger editor's petstore, this would be the json body example for the POST /pet API:

{
  "id": 0,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}

But this JSON example isn't included in the Swagger2Markup documentation.

So my question is, is it possible to update Swagger2Markup (or change the Swagger2Markup properties) to include JSON body API examples in the final document?

If not, is there a different way you recommend converting Swagger YAML into a readable document that includes JSON body API examples?

Upvotes: 2

Views: 922

Answers (1)

Sammy Cakes
Sammy Cakes

Reputation: 162

To add json body API examples to the adoc with swagger2markup, create a config file (config.properties) and add "swagger2markup.generatedExamplesEnabled=TRUE". Per the swagger2markup reference document, section 3.2.5, this property specifies if http rquest and response examples should be generated. Awesome!

Upvotes: 2

Related Questions