I'm trying to integrate an existing flask app with OpenAPI (Swagger), to generate its documentation and use Swagger UI. How should I do this?
The best solution (expected behaviour with least changes) for me was to use connexion, and use OpenAPI Specifications to replace the routes layer. Instead of using Flask "directly", a connection app was created.
app = connexion.App(__name__, specification_dir='swagger/')
app.add_api('my_api.yaml')
app.run(port=8080)
https://github.com/zalando/connexion
Related
I am trying to introduce URL versioning into my .Net Core WebAPI application. I am also using Swagger web tools for ease of use for users.
Now, while trying to introduce versioning into my application, I referenced the docs here: https://github.com/Microsoft/aspnet-api-versioning/wiki/New-Services-Quick-Start#aspnet-core
Now, I made following code changes into my code:
Startup.cs/ConfigureServices I added code below:
services.AddApiVersioning(options => {
options.AssumeDefaultVersionWhenUnspecified = true;
});
Now, my controller annotations before any kind of versioning was added, looked like below:
[Produces("application/json")]
[Route("api/controllerName")]
and produces a URL which looks like something below:
http://localhost:12003/swagger/#!/Workspace/GetAll
Now, I added annotations below to enable api versioning:
. [ApiVersion("1.0")]
[Produces("application/json")]
[Route("api/v{version:apiVersion}/workspace")]
and now when I click on the same method listed in my swagger UI
the url looks like below:
http://localhost:12003/swagger/#!/controllername/ApiV_versionGetAll
While what I was expecting was something like:
http://localhost:12003/swagger/#!/controllername/V1.0/GetAll
Also on my swagger it is now asking me explicitly about entering version number. So I think my question boils down to two major points:
How I can I fix my URL? and what am I doing wrong?
Why is swagger now asking me to enter version number in API UI when I have explicitly stated that the version is going to be 1.0 in the annotation of the controller?
What you are missing is the complementary package for API versioning that supports an API version-aware API Explorer:
https://www.nuget.org/packages/Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
Install-Package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
The API Explorer is how Swagger generators like Swashbuckle do all their work. The source and links are also available in the API versioning repo.
To achieve the result you want, you need to configure API version substitution in the URL:
services.AddMvcCore().AddVersionedApiExplorer( options => options.SubstituteApiVersionInUrl = true );
Note: that the call the AddMvcCore() is no longer required in API Versioning 3.0+
Documentation and samples are available in the official API versioning repo. I recommend reviewing the API Documentation wiki topic:
https://github.com/Microsoft/aspnet-api-versioning/wiki/API-Documentation
The accepted answer extends this package, which is fine as long as it stay up-to-date with the flavor of API versioning you are using. API Versioning always ships compatible API Explorer extensions on every release.
Setting up api versioning with swagger is indeed a tricky thing as it is lot's of pieces that need to be setup correctly.
Luckily for us, there's a great nuget packages called SwashbuckleAspNetVersioningShim which solves this in an excellent way.
Add it
Install-Package SwashbuckleAspNetVersioningShim -Version 2.2.1
Then follow the readme here
I've got a program which creates JIRA issues using the jira-rest-api supported by Atlassian.
What I'd like to do is to create a link within the issue to an external URL (actually a presigned Amazon S3 link).
At the REST level this should be doable with a POST request to the Jira api to create a remoteLink. However I cannot find methods in the client APIs or a RemoteLink dto in the Java library.
Nor does the Java library appear to give any access to lower level REST handlers.
Now, I could set up my own REST handling code, going right back to the endpoint URL and authentication, but that's messy, when most of the code the code should already be there. Also I can't clearly see which json fields are required, and which not can be left to the API.
Am I overlooking something obvious in the documentation? I can't even seem to locate source for the client implementation, only the interface layer.
My current code is using version 3.0.6 of the api, but I've just checked v4 (which seems to be the latest on offer) and there's still no RemoteLink support.
Have you tried with these?
Server: https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/?_ga=2.26380925.1321063199.1523351418-1788196903.1491202928#api/2/issue-deleteRemoteIssueLinkById
Cloud: https://developer.atlassian.com/cloud/jira/platform/rest/#api-api-2-issue-issueIdOrKey-remotelink-linkId-delete
What is the best way to version API?
For example I am using sails js for API backend, to version the API:
Should it be done in my application, (in the controller) (at app level)?
Should I use the routes.js for versioning the API (framework level)?
Should I do it with nginx (server level)?
Should it be done at API Gateway (API Management)?
My approach for api versioning is at application level:
Create subfolder for your controllers as:
/controllers/v1/UserController.js
/controllers/v2/UserController.js
In your routes.js file, add as follow:
'POST /api/v2/user': 'v2/UserController.create',
'POST /api/v1/user': 'v2/UserController.create',
And in your policies.js, you can add middlewares like this:
'v2/UserController': {
'create': ['isAuthenticated','isAuthorized']
}
My current sails' version is: 0.12.3.
At this time, model versioning is not supported by using subfolders.
In the guide for Yii 2 it is said:
While not required, it is recommended that you develop your RESTful
APIs as a separate application, different from your Web front end and
back end for easier maintenance.
Source: RESTful Web Services - Quick Start
What does this mean? Would this be a completely different application or can it be in the same folder as the 'normal' web application? I've just started with my application so I can change things easily, more or less. But I'm wondering: if I would create another application than my business logic would not be accessible.
Why and how I should create another application? And when it's not required?
It means you have to create an application like frontend or backend(Yii 2 advanced application template),
what you have to do is create another directory call 'api' same as backend or frontend, and it'll contain folder structure same as backend|frontend except assets, views, widgets etc.
Basically you need folder structure like this
api
-config
-modules
--v1
---controllers
---models
-runtime
-tests
-web
backend
common
console
environments
frontend
If you'r going to use Yii 2 basic application template to develop rest api, it's posible. create module call 'api' and create a sub directory call 'v1' as sub-module.
(Yii doc -A module may consist of sub-modules.)(GiovanniDerks - backend sub-modules)
-modules
--api
---v1
----controllers
----models
There is an advantage of using one of these folder structure, because you don't have to worry about route much.
https://domain.com/api/v1/products
Here is good example for RESTful API with advance template
Setup RESTful API in Yii2(budiirawan)
API & RESTFull API are different. RESTFull APIs have to have REST standards. basically that's why APIs are developed as separate application. in normal app, we create 4 actions for CRUD functions. but in yii2 RESTFull API we just create One action for all CRUD functions. (Controllers extend from REST Active Controller - yii\rest\ActiveController ). in core code you can find find 4 actions for different headers GET,POST,PUT & DELETE .
'index' => ['GET', 'HEAD'],
'view' => ['GET', 'HEAD'],
'create' => ['POST'],
'update' => ['PUT', 'PATCH'],
'delete' => ['DELETE'],
for authentication basically we can use 'HTTP Basic Authentication'
This article explain the idea and the why , also it provide you a starter project called "yii2-advanced-api": http://budiirawan.com/setup-restful-api-yii2/
IMHO if you need REST API for Angular.js or Knockout.js AJAX calls on your website it's an overhead to do it as a separate application. Because you will have issues with cross-domain AJAX calls (especially for POST requests).
I think it's enough to make a module (API) in the frontend for REST API
I've made simple nodejs application by using nodejs+express. Now I want to make user authentification. I want to realize session handling by using mongoose.
Can you advise some example?
Some useful links:
how to implement login auth in node.js
creating registration and login form in node.js and mongodb
Also session management isn't done by Mongoose, but by connect-mongodb or connect-redis. You can checkout an example on how to do user auth and session management in a real application here:
https://github.com/alexyoung/nodepad/blob/master/app.js
Further explanations for that app you can find here: http://dailyjs.com/tag/lmawa or http://dailyjs.com/2010/12/06/node-tutorial-5/
Just use mongoose-auth by Brian Noguchi https://github.com/bnoguchi/mongoose-auth
It's a drop in solution for your question, it's well documented and extensible.
EDIT
mongoose-auth is no longer maintained. If you need to make it work with more recent versions of mongoose (ie > v3.x.x) and express (ie. > v3.x.x), here's an excerpt from a package.json file I'm currently using in production (It's hacky but it works):
"everyauth": "https://github.com/bnoguchi/everyauth/tarball/express3",
"mongoose-3x-types": "~1.0.5",
"mongoose-auth": "https://github.com/cbou/mongoose-auth/tarball/everymodule-fix",
I you are starting a new project don't use mongoose-auth, instead try out passport. It offers the same functionality, it's very flexible, however it has a different api. It's part of the locomotive MVC framework and as such it's actively maintained.
I've posted a complete example of a complete auth system using mongoose + expressjs on here, in case you want to take a look:
Simple login page in nodejs using express and passport with mongodb