Generate WebAPI documentation in swagger json format

Question

I have created a WebAPI using .Net 4.5 and want to document this API using Swagger. I have added swagger-ui in my .Net project. Now when i browse to ../swagger-ui/index.html it successfully opens pet store api-docs (json) in swagger UI format.

My question is how can I create such (swagger) json for my WebAPI controllers and models? As I have put in required XML summaries/comments to c# classes and attributes.

I saw that Swagger.Net and Swashbuckle are there doing similar things but I could not really understand how to generate swagger-json file using any of them. There might be very small mistake I am doing but unable to point out.

Please help.

I want to do opposite to this http://stackoverflow.com/questions/10560857/swagger-with-static-documentation — theGeekster, Jan 24 '14 at 15:35
Did you find any solution to the question? I'm also interesting in generation of json spec without running a web server. — Shrike, Nov 14 '14 at 12:06
No, I couldn't find any solution yet, which supports WebAPI's Attribute Routing. — theGeekster, Nov 20 '14 at 08:21

Matt Frear · Answer 1 · 2017-09-12T19:55:21.710

27

As stated, /swagger takes you to the swagger UI.

If you're using Swashbuckle, then /swagger/docs/v1 should take you to the swagger.json file - I found this using Chrome Dev tools.

Edit: if you're using Swashbuckle.AspNetCore, then the url is slightly different - /swagger/v1/swagger.json

edited Sep 12 '17 at 19:55

answered Apr 16 '15 at 14:25

Matt Frear

52,283
12
78
86

Thats if you are using Swashbuckle. – Peter Marshall Jun 12 '15 at 10:05

score 4 · Answer 2 · answered Feb 11 '14 at 18:41

You need to integrate Swagger.NET into your project so that you end up with the following controller:

public class SwaggerController : ApiController { /* snip */ }

and you should also have the following route registered:

context.Routes.MapHttpRoute (
name : "Swagger",
routeTemplate: "api/swagger"
defaults: new
{
  controller = "Swagger",
  action = "Get",
});

assuming that is working you should be able to call /api/swagger and get something like the following:

{
  apiVersion: "4.0.0.0",
  swaggerVersion: "2.0",
  basePath: "http://localhost:5555",
  resourcePath: null,
  apis: [
  {
    path: "/api/docs/Values",
    description: "No Documentation Found.",
    operations: [ ]
  },
  {
    path: "/api/docs/Home",
    description: "No Documentation Found.",
    operations: [ ]
  }
]

}

then in SwaggerUI/index.html you'll want to update the discoveryUrl:

<script type="text/javascript">
    $(function () {
        window.swaggerUi = new SwaggerUi({
            discoveryUrl: "http://localhost:5555/api/swagger",
            apiKey:"",
            dom_id:"swagger-ui-container",
            supportHeaderParams: false,
            supportedSubmitMethods: ['get', 'post', 'put']
        });

        window.swaggerUi.load();
    });
</script>

That's again runtime version of doc. We have to run a web server to get/show doc. But the question was about how to generate a json spec. I'm also interested in this topic - I need to generate a json Swagger spec file on build. — Shrike, Nov 14 '14 at 12:04
Swagger.Net will generate the json spec for you using the ASP.NET ApiExplorer. If you need to save the json spec file for some reason then just call the url and save the results to a file. — Todd Smith, Nov 21 '14 at 19:25
Some data will always be available only at runtime, this is why you need to run the service. For instance the routes will be defined by code, so a static analysis would not be able to guess the actual routes without running the service. — Sébastien Ros - MSFT, Jan 22 '15 at 00:48

score 1 · Answer 3 · answered Sep 14 '17 at 12:14

1

You can use "NSwagStudio" desktop application to load the json document without running the api project. By providing the api assembly.

https://github.com/RSuter/NSwag/wiki/NSwagStudio

Download the (NSwagStudio) windows desktop application.

answered Sep 14 '17 at 12:14

velmurugan

19
1
3

Generate WebAPI documentation in swagger json format

3 Answers3