{"id":1979,"date":"2015-09-21T19:34:26","date_gmt":"2015-09-21T17:34:26","guid":{"rendered":"http:\/\/developex.com\/blog\/?p=1979"},"modified":"2025-08-07T21:55:43","modified_gmt":"2025-08-07T19:55:43","slug":"sharing-the-api-with-swagger-api-framework","status":"publish","type":"post","link":"https:\/\/developex.com\/blog\/sharing-the-api-with-swagger-api-framework\/","title":{"rendered":"Sharing the API with Swagger API Framework"},"content":{"rendered":"Every manager or project owner wants to control development of their software but not all are able to do it. Aiming to make development clear for all participants of project the DevelopEx company has started to use the Swagger Framework \u2014 a tool for REST API representation and interactive documentation. That is especially useful for popular approach where we separate (web) services from front-end. Now the team members are able to view not only front-end of the project, but also play with back-end. And see how does it works inside.\n\nFor one of our project we use our own API that written with ASP.NET WebApi<\/a>. Our API implements a set of operations with common entities such as 'Client<\/em>', 'User<\/em>', 'Order<\/em>', 'Certificate<\/em>' and so on. And we use Swagger rules to describe the API. Since we did it we've got well described REST API methods that helped both customer, and developers and testers.The project became more clear and more stable.\n\nLet's look at the User interface and the code for small part of API that is described by Swagger.\n

User Interface<\/h3>\nScreenshot #1<\/strong> represents common general view of our API that converted to REST API by Swagger Framework. In our sample we have objects of API such as Certificates, Clients, Dummy, etc.\n\n
\"Screenshot

Screenshot #1 - common general view of our API that converted to REST API by Swagger Framework<\/p><\/div>\n\nLet's see how both DevelopEx's customer and our testers could estimate functionality the Client API. Look at the Screenshot #2<\/strong>, the right side of it shows JSON structure of data for Client entity.\n\n

\"Look

Look at the Screenshot #2, the right side of it shows json-structure of data for Client entity.<\/p><\/div>\n\nFor Client also accessible different API's responses that will be in case of 1) valid values or 2) wrong values (ClientRegisterResponse<\/em> and ValidationErrorResponse<\/em> respectively, Screenshot #3<\/strong>) when we try to create a new Client.\n\n

\"For

For Client also accessible different API's responses that will be in case of 1) valid values or 2) wrong values (ClientRegisterResponse and ValidationErrorResponse respectively, Screenshot #3) when we try to create a new Client.<\/p><\/div>\n\nBut how to check it? Click on data type of Client entity, immediately its structure is copied to the left side of Client viewer and stay editable. Input needing data ('string<\/em>' for string, etc.), press 'Try it<\/strong>' button and see how the API treat the request.\n\nThe behavior of such interactive documentation is strictly the same as behavior of real functions inside the application that works on the real data base. Let's fill the email field with 'foo@bar.com<\/em>' value first time and send the request (displayed on the Listing #1<\/strong>). Then try to send the second request with the same email. Oops, the Swagger Framework says something like this (see Listing #2<\/strong>):\n

curl \"https:\/\/................\/Swag2.Web\/api\/v2\/geeks\/register\" -H \"Content-Type: application\/json\" -H \"Accept: application\/json\"  -data-binary \"{\"^\n\"  \"\"rate\"\": 0,\"^\n\"  \"\"phone\"\": \"\"0958317000\"\",\"^\n\"  \"\"description\"\": \"\"\"\",\"^\n\"  \"\"offlineLocation\"\": \"\"\"\",\"^\n\"  \"\"isPhoneMobile\"\": true,\"^\n\"  \"\"workOptions\"\": \"\"remote\"\",\"^\n\"  \"\"firstName\"\": \"\"Michael\"\",\"^\n\"  \"\"lastName\"\": \"\"Jackinson\"\",\"^\n\"  \"\"email\"\": \"\"mjack@domain.com\"\",\"^\n\"  \"\"password\"\": \"\"123\"\",\"^\n\"  \"\"confirmPassword\"\": \"\"123\"\",\"^\n\"  \"\"socialProviderName\"\": \"\"string\"\",\"^\n\"  \"\"socialProviderToken\"\": \"\"string\"\"\"^\n\"}\" --compressed\n<\/pre>\n
Listing #1<\/h5>\n
HTTP\/1.1 422 Unprocessable Entity\nCache-Control: no-cache\nPragma: no-cache\nContent-Type: application\/json; charset=utf-8\nExpires: -1\nX-Request-Id: 0dda489f-dafd-479e-80af-0154e0128237\nDate: Thu, 10 Sep 2015 15:57:02 GMT\nContent-Length: 344\n{\n  \"errors\": [\n    {\n      \"field\": \"email\",\n      \"message\": \"Email already exists\",\n      \"code\": \"emailExists\"\n    }\n  ],\n  \"message\": \"Validation failed\"\n}\n<\/pre>\n
Listing #2.<\/h5>\nIn case of correct values we receive something like on the Screenshot #4<\/strong>.\nThere is nothing like clear code, isn't it?!\n\n
\"In
In case of correct values we receive something like on the Screenshot #4.
There is nothing like clear code, isn\u2019t it?!<\/p><\/div>\n
Code<\/h3>\nFinally, let's look at those part of code where REST API describes new client registration.\n
\/\/ POST api\/v2\/clients\/register\n\/\/\/\n\n\/\/\/ Registers new client\n\/\/\/\n[HttpPost]\n   [Route(\"register\")]\n     [SwaggerResponse(201, \"Created\", typeof(ClientRegisterResponse))]\n\n     [SwaggerResponse(422, \"Validation error\", typeof(ValidationErrorResponse))]\npublic async Task Register([FromBody] ClientRegisterRequest request)\n{\n     ...\n}\n<\/pre>\n
Listing #3.<\/h5>\n[SwaggerResponse<\/strong>] are attributes that Swagger uses to define how the API should proceed the queries.\nDefinitely, the visible part of User Interface and the code is the small part of all sides of interfaces and codes that the Swagger provides. But we showed the essentials:\n
    \n \t
  1. clear code for all: developers and customer,<\/li>\n \t
  2. ability to check a software deeply and easier, for both testers and customer too.<\/li>\n<\/ol>","protected":false},"excerpt":{"rendered":"
    Every manager or project owner wants to control development of their software but not all are able to do it. Aiming to make development clear for all participants of project the DevelopEx company has started to use the Swagger Framework \u2014 a tool for REST API representation and interactive documentation. That is especially useful for popular approach where we separate (web) services from front-end. Now the team members are able to view not only front-end of the project, but also play with back-end. And see how does it works inside. For one of our project we use our own API that written with ASP.NET WebApi. Our API implements a set of operations with common entities such as ‘Client’, ‘User’, ‘Order’, ‘Certificate’ and so on. And we use Swagger rules to describe the API. Since we did it we’ve got well described REST API methods that helped both customer, and developers and testers.The project became more clear and more stable. Let’s look at the User interface and the code for small part of API that is described by Swagger. User Interface Screenshot #1 represents common general view of our API that converted to REST API by Swagger Framework. In our sample we have objects of API such as Certificates, Clients, Dummy, etc. Screenshot #1 – common general view of our API that converted to REST API by Swagger Framework Let’s see how both DevelopEx’s customer and our testers could estimate functionality the Client API. Look at the Screenshot #2, the right side of it shows JSON structure of data for Client entity. Look at the Screenshot #2, the right side of it shows json-structure of data for Client entity. For Client also accessible different API’s responses that will be in case of 1) valid values or 2) wrong values (ClientRegisterResponse and ValidationErrorResponse respectively, Screenshot #3) when we try to create a new Client. For Client also accessible different API’s responses that will be in case of 1) valid values or 2) wrong values (ClientRegisterResponse and ValidationErrorResponse respectively, Screenshot #3) when we try to create a new Client. But how to check it? Click on data type of Client entity, immediately its structure is copied to the left side of Client viewer and stay editable. Input needing data (‘string’ for string, etc.), press ‘Try it’ button and see how the API treat the request. The behavior of such interactive documentation is strictly the same as behavior of real functions inside the application that works on the real data base. Let’s fill the email field with ‘foo@bar.com’ value first time and send the request (displayed on the Listing #1). Then try to send the second request with the same email. Oops, the Swagger Framework says something like this (see Listing #2): curl “https:\/\/…………….\/Swag2.Web\/api\/v2\/geeks\/register” -H “Content-Type: application\/json” -H “Accept: application\/json” -data-binary “{“^ ” “”rate””: 0,”^ ” “”phone””: “”0958317000″”,”^ ” “”description””: “”””,”^ ” “”offlineLocation””: “”””,”^ ” “”isPhoneMobile””: true,”^ ” “”workOptions””: “”remote””,”^ ” “”firstName””: “”Michael””,”^ ” “”lastName””: “”Jackinson””,”^ ” “”email””: “”mjack@domain.com””,”^ ” “”password””: “”123″”,”^ ” “”confirmPassword””: “”123″”,”^ ” “”socialProviderName””: “”string””,”^ ” “”socialProviderToken””: “”string”””^ “}” –compressed Listing #1 HTTP\/1.1 422 Unprocessable Entity Cache-Control: no-cache Pragma: no-cache Content-Type: application\/json; charset=utf-8 Expires: -1 X-Request-Id: 0dda489f-dafd-479e-80af-0154e0128237 Date: Thu, 10 Sep 2015 15:57:02 GMT Content-Length: 344 { “errors”: [ { “field”: “email”, “message”: “Email already exists”, “code”: “emailExists” } ], “message”: “Validation failed” } Listing #2. In case of correct values we receive something like on the Screenshot #4. There is nothing like clear code, isn’t it?! In case of correct values we receive something like on the Screenshot #4.There is nothing like clear code, isn\u2019t it?! Code Finally, let’s look at those part of code where REST API describes new client registration. \/\/ POST api\/v2\/clients\/register \/\/\/ \/\/\/ Registers new client \/\/\/ [HttpPost] [Route(“register”)] [SwaggerResponse(201, “Created”, typeof(ClientRegisterResponse))] [SwaggerResponse(422, “Validation error”, typeof(ValidationErrorResponse))] public async Task Register([FromBody] ClientRegisterRequest request) { … } Listing #3. [SwaggerResponse] are attributes that Swagger uses to define how the API should proceed the queries. Definitely, the visible part of User Interface and the code is the small part of all sides of interfaces and codes that the Swagger provides. But we showed the essentials: clear code for all: developers and customer, ability to check a software deeply and easier, for both testers and customer too.<\/p>\n","protected":false},"author":4,"featured_media":21403,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[1175,1170],"tags":[334,150,622,623,624,563,625,626],"class_list":["post-1979","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-all-categories","category-technical-implementation","tag-api","tag-asp-net","tag-back-end","tag-framework","tag-front-end","tag-rest","tag-rest-api","tag-swagger"],"aioseo_notices":[],"_links":{"self":[{"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/posts\/1979","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/comments?post=1979"}],"version-history":[{"count":1,"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/posts\/1979\/revisions"}],"predecessor-version":[{"id":30204,"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/posts\/1979\/revisions\/30204"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/media\/21403"}],"wp:attachment":[{"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/media?parent=1979"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/categories?post=1979"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/developex.com\/wp-json\/wp\/v2\/tags?post=1979"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}