I've got Koa/Express apps and would like to generate a static documentation based on annotations to the different API routes.
Swagger seems to be good but all packages I found don't generate the documentation but host it with the API itself.
I want the API documentation to be seperated from my API.
Are there modules other OS projects offering this?
Given that you've the OpenAPI/Swagger spec, you can try Swagger Codegen by going to https://editor.swagger.io. Under "Generate Client" select "HTML" or "Dynamic HTML"
Or you can use https://restunited.com to generate both SDKs and documentation with code sample. Here is an example: http://restunited.com/docs/6y2jvtvkgvst
Disclosure: I'm a top contributor to Swagger Codegen and founder of RESTUnited.com
Related
so i am able to call app insight's api "https://api.applicationinsights.io/v1/apps/xx/xx/xx" from my C# code.
i can get the json response.
i have this response in json and i want to serialize it into C# objects. do i have to create matching C# classes my self or is there any built in c# models i can use and serialize them?
Not really a direct answer to your question, but instead of consuming REST API directly and doing the conversion/serialization yourself you can simply use Application Insights .Net SDK.
The SDK will do all the necessary conversions for you and give you nice C# objects. The source code for this is also open source and is available here: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/applicationinsights/Microsoft.Azure.ApplicationInsights.Query.
You can take a look here for all the models available to you for direct use here: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/applicationinsights/Microsoft.Azure.ApplicationInsights.Query/src/Generated/Models.
In my opinion, if you choose to use app insights api, that means you didn't add any other sdk into your project, that means there's no any built in models for you.
And if you choose to use sdk instead, here's a sample for it, and per my testing, it only provides QueryResults as the response, here's my testing result， and this is the introduction for preparation. Pls note, you need wait for a while to make the newly added role to take effect. If you can't find the api permission mentioned in the document, you can search for it like what I did.
I have created an API using Swagger.
My customers will be able to make calls to my service like
https://theservice.com/data/items/category1/12345
This is fine and works ok.
However, I would like to have a page where they can see all available API calls, similar to how Swagger generates it on their SwaggerEditor app. For example by visiting https://theservice.com/index.html I would like them to see the API docs.
Is it possible (within Swagger) to do this on a live system (not just locally with swagger project edit which I already know)?
If yes, how?
It sounds like you're using the Swagger Editor to describe your API, then generating some scaffolding code using the built-in generator. From your tags, I assume this is node.js code. You'll need to add your own logic to the generated code to complete this API implementation (if you haven't already done so).
If this is correct, then the interactive Swagger-UI documentation you're looking for should be available in your generated API at /docs endpoint, relative to the base URL of your running service.
The generated node.js project includes the Swagger spec you created in the editor, and uses Swagger-Tools to do the runtime magic. Among other things, Swagger-Tools auto-wires your Swagger spec to the /docs endpoint, and manages routing of requests to the generated controllers, based on information provided in your Swagger spec.
Note that the /docs page will look and behave somewhat differently from the documentation widget you see in the Swagger editor. The one in your application uses Swagger-UI, which is the runtime component for documentation, with interactive sandbox testing. Swagger-Editor has its own built-in documentation UI, and this is not currently packaged for use outside of the Swagger-Editor.
If you've already implemented an API, independent of the Swagger editor and code generator, you can still generate node.js code to see how to incorporate Swagger-Tools into your existing API implementation. Or, as wing328 suggests, take a look at Swagger-UI to see how you can add your own documentation page.
I think what you're looking for is swagger-ui and here is an example: http://petstore.swagger.io/
As you can see, it not only lists out all the available API endpoints but also lets visitors (developers) to try it out directly in the web page.
I wanted to know what are the pre-requisites required to learn swagger in node.js and what is the role of swagger in node.js . Do I need to learn YAML for it? It would be helpful to know where I can find more information on swagger and its training.
Swagger is a way to document your REST service. Its not tied to any Server side technology. Swagger can be used to document Rest services built with Java, Go or any other Tech stack.
To answer your questions.
pre-requisites required to learn swagger in node.js? ---- You should be
really familiar with your contract part of your webservice. It will
be helpful if you are a bit familiar with Json or Yaml file
what is the role of swagger in node.js? ---- To document the Rest services
built with NodeJs (or any other server side technology , for that
matter)
Do I need to learn YAML for it? ---- Not necessarily. You can do either
in Json or Yaml (My personal preference is Json, because whitespace
doesn't really mean much there)
editor.swagger.io has a nice tool with which you can validate your swagger spec, convert between json and yaml formats etc.
Take a look here http://editor.swagger.io/#/ , play a bit with swagger spec of Uber API.
Swagger specification document is not being generated from Swagger integration into Node.js project as a sub project. However, SwaggerUI is up and running. If we provide say swagger.json or api-docs.json file then it is rendering specified REST API calls.
My requirement is to generate the API document for existing project. How do I do it ?
See this answer for help in deciding how to generate Swagger docs for a project.
You can either manually create the docs for your API and have Swagger UI serve them, or you can use a node package like swagger-node-express which will do most of the documenting automatically. See the link above for pros and cons of each of these options.
Is there any quick way to automatically generate HAR for ServiceStack Services to be used for API Documentation tools like API Embed?
Why don't you use existing tools?
With Swagger API your API will be automatically documented and testable.
If you prefer, you can use ServiceStack Metadata page too. It's less sexy than Swagger, but it's ok, it does the job.