{"id":28861,"date":"2018-10-15T09:08:49","date_gmt":"2018-10-15T07:08:49","guid":{"rendered":"https:\/\/mamchenkov.net\/wordpress\/?p=28861"},"modified":"2018-10-15T09:09:13","modified_gmt":"2018-10-15T07:09:13","slug":"documenting-lists-with-swagger","status":"publish","type":"post","link":"https:\/\/mamchenkov.net\/wordpress\/2018\/10\/15\/documenting-lists-with-swagger\/","title":{"rendered":"Documenting lists with Swagger"},"content":{"rendered":"\n

Swagger<\/a> is a great tool for documenting APIs.\u00a0 Not only it helps with keeping the documentation complete and up-to-date, but it also provides a handy sandbox for developers to play around with the API directly from the documentation.<\/p>\n

We use Swagger a lot at work<\/a>.\u00a0 We’ve even pushed the bar slightly, but automatically generating the API documentation on the fly, to match the rest of our Qobrix<\/a> functionality.\u00a0 Whenever you change the database schema or the configuration of the fields, the changes are also reflected immediately in the API documentation.\u00a0 And it works great!<\/p>\n

One of the things that we haven’t done though until very recently is the documentation of the list fields.\u00a0 Swagger provides the enum<\/a> to document the values that can go into the field, but it’s not very helpful, when the values are not obvious.\u00a0 Country codes and currency symbols work well, as they are common knowledge.\u00a0 But if you have something custom, there needs to be a set of labels associated with the set of values.<\/p>\n

The other day we decided that something is better than nothing, and added the documentation of the values as part of the field description (the property is described on the same page as enum above).\u00a0 Here’s the Pull Request<\/a> with the tiniest of changes.\u00a0 And here’s how it looks in Swagger:<\/p>\n

\"\"<\/a>I admit, it’s not the prettiest of things, but at least the hints for the developers are there.\u00a0 Also, since the list of labels uses a specific format, it’s quite easy to parse it out of the Swagger JSON automatically and reuse in third-party applications and services (like a website, connected to the system via the API).<\/p>\n

While browsing around, I’ve also noticed that Swagger is growing and expanding. There is a new version of the specification – version 3.0, which has also been re-branded as OpenAPI Specification<\/a>\u00a0(see OpenAPI Initiative<\/a>).\u00a0 Here’s a great blog post<\/a> that describes the differences between this and the previous versions, and here’s the migration guide<\/a> for those who need it.<\/p>\n

If you are working with PHP,\u00a0zircote\/swagger-php<\/a> is the way to go.\u00a0 It already even support the version 3.0.\u00a0 If you are using the CakePHP framework,\u00a0alt3\/cakephp-swagger<\/a> is the plugin for you (version 3.0 is not yet supported, but I’m sure it’ll get there soon).<\/p>\n\n","protected":false},"excerpt":{"rendered":"\n

Swagger is a great tool for documenting APIs.\u00a0 Not only it helps with keeping the documentation complete and up-to-date, but it also provides a handy sandbox for developers to play around with the API directly from the documentation. We use Swagger a lot at work.\u00a0 We’ve even pushed the bar slightly, but automatically generating the … Continue reading Documenting lists with Swagger<\/span><\/a><\/p>\n\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_feature_clip_id":0,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2},"jetpack_post_was_ever_published":false,"_links_to":"","_links_to_target":""},"categories":[1,18,62,1334],"tags":[2404,3069,1537,78,3601,38,1216,3602,1330],"keyring_services":[],"class_list":["post-28861","post","type-post","status-publish","format-standard","hentry","category-general","category-programming","category-technology","category-web-work","tag-api","tag-best-practices","tag-cakephp","tag-documentation","tag-openapi","tag-php","tag-standards","tag-swagger","tag-web-development"],"aioseo_notices":[],"aioseo_head":"\n\t\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t