My swagger.json (paths) file looks like
"paths": {
"/auth/forgot-password": {
"$ref": "../auth/forgot-password/post.json"
}
}
and inside forgot-password/post.json there are included files
"responses": {
"200": {
"$ref": "../responses/default.json#/success"
},
"403": {
"$ref": "../responses/default.json#/forbidden"
},
"404": {
"$ref": "../responses/default.json#/notFound"
}
}
I am curious if there is any chance to divide Swagger paths into separated files without fetching all on rendering page. Actually I made it to work but now I have a problem with response time because as I mentioned it will fetch all included files (one by one) which I don't want/need. (as more included files I have as bigger response time will be).
So my question should be: is there any way for this case to fetch only swagger.json not and forgot-password/post.json and responses/default.json?
These two files should be fetched only if user clicks to extend accordion to see specific endpoint.
We want to have a system that allows us to define data schemas that we can use to validate our data, and to generate code in specific languages. We found json schema's that lets us do something like
File "message.json.schema"
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "Message",
"properties": {
"name": {
"type" : "string"
},
"type": {
"$ref": "type/message_type.schema.json"
},
"message_id":{
"$ref": "type/uuid.schema.json"
}
},
"required": ["name", "message_id"]
}
File "message_type.json.schema"
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "MessageType",
"enum": ["Message", "Query"]
}
File "uuid_type.json.schema"
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "UUID",
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
File "query.json.schema"
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "Query",
"allOf" : [ {"$ref": "type/message.schema.json" }],
"required": ["type"]
}
Please ignore if there is something that doesn't make sense but the point is, we really enjoy this system because it allows us to define types, and to refer to types that we create in another files, and even to use them like for type inheritance.
Then we want to use this files for code generation and validation. In python we then use a library called python_jsonschema_objects that can parse this files and the files that it references recursively, and we can then really simply create a python object with all the validation included.
But then we also want to use them for Java/Kotlin but the library that we found jsonschema2pojo doesn't seem able to parse linked files expecting everything to be in the same file.
This leads us to think that for some reason Json Schema is not that supported or used, unfortunately.
So, we have the question if a system like Avro or OpenAPI would be better supported and more widely used and could be chosen to this type of task.
I have my API documented and versioned previously using Swashbuckle.AspNetCore, Microsoft.AspNetCore.Mvc.Api.Analyzers, Microsoft.AspNetCore.Mvc.Versioning and Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer.
Everything was fine but all of a sudden today I noticed that JsonPatchDocument Not getting displayed properly in my swagger. I couldn't figure out what's the root cause. But I suspect some Nuget Package Upgrade?
Previously I remember the JsonPatchDocument in my swagger as something similar below:
{
"Operations": [
{
"value": {},
"path": "string",
"op": "string",
"from": "string"
}
]
}
But now it shows something else,
{
"ContractResolver": {}
}
Please assist on what I'm missing
Make sure you are added the AddNewtonsoftJson in program.cs after install the Microsoft.AspNetCore.Mvc.NewtonsofJson
should be like this :
builder.Services.AddControllers().AddNewtonsoftJson();
Imagine you are working under following circumstances:
You have REST API modules with API documentation generated into swagger-ui.html
Possible HTTP status codes for endpoints are documented well via io.swagger.annotations.* on controller method level for each endpoint.
In case of some error state (4XX or 5XX) application replies with ErrorResponseDTO with structure like
"ErrorResponseDTO": {
"type": "object",
"properties": {
"errorCode": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
Application have tens of errorCodes (within range like 1 - XX and please consider them as a legacy definiton without an easy way to change them).
List of errorCodes is relevant for the whole application so you prefer to keep their definiton list/table in overall API documentation rather then maintaining errorCodes definiton for each API endpoint separately.
Now you are looking for an effective way how to document these application error codes into API contract.
The approach of including a list of errorCodes with codes description into generated swagger-ui.html seems like a better way to keep API documentation up to date instead of having static and handwritten codes definition table attached in Markdown format in some Readme file.
Would you please have any recommendation how to document various codes which your applications produce?
Do you follow some specific good practice in this topic?
Thank you in advance.
Meanwhile within a small internal dev team and with frequent API extensions there can be used generated swagger-ui with included error codes:
#Bean
public Docket swaggerSettings() {
ApiSelectorBuilder builder = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(
new ApiInfoBuilder()
.title("Response errorCodes table")
.description(RestResponse.generateErrorsDocumentation().toString())
.build()
)
...
.select();
return builder.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build()
.useDefaultResponseMessages(false);
}
I can't figure out or find the documentation on how to access the source of an old commit in the new Bit Bucket format. Is this even possible anymore?
I understand you want to download an older version via the BitBucket web interface without using a Mercurial/Git client.
Check this related question. On the comments, someone says that there is no way to do that. Fortunately, that's not entirely true.
By navigating on BitBucket project pages, I found no link to download an arbitrary version. There are links to download specific tags, in the format:
https://bitbucket.org/owner/repository/get/v0.1.2.tar.gz
But by tweaking a bit the url above, changing the tag name by the commit hash, like:
https://bitbucket.org/owner/repository/get/A0B1C2D.tar.gz
You can actually download a specific version.
As mentioned by Rakka Rage in a comment, replacing .tar.gz by .zip works too.
I was trying to figure out if it's possible to browse the code of an earlier commit like you can on GitHub and it brought me here. I used the information I found here, and after fiddling around with the urls, I actually found a way to browse code of old commits as well.
When you're browsing your code the URL is something like:
https://bitbucket.org/user/repo/src/
and by adding a commit hash at the end like this:
https://bitbucket.org/user/repo/src/a0328cb
You can browse the code at the point of that commit. I don't understand why there's no dropdown box for choosing a commit directly, the feature is already there. Strange.
Step 1
Step 2
Step 3
Step 4
Final Step
Just in case anyone is in my boat where none of these answers worked exactly, here's what I did.
Perhaps our in house Bitbucket server is set up a little differently than most, but here's the URL that I'd normally go to just to view the files in the master branch:
https://<BITBUCKET_URL>/projects/<PROJECT_GROUP>/repos/<REPO_NAME>/browse
If I select a different branch than master from the drop down menu, I get this:
https://<BITBUCKET_URL>/projects/<PROJECT_GROUP>/repos/<REPO_NAME>/browse?at=refs%2Fheads%2F<BRANCH_NAME>
So I tried doing this and it worked:
https://<BITBUCKET_URL>/projects/<PROJECT_GROUP>/repos/<REPO_NAME>/browse?at=<COMMIT_ID>
Now I can browse the whole repo as it was at the time of that commit.
Great answers from a couple of years ago. Now Bitbucket has made it easier.
Tag the Commit you want to download (as mentioned in answer by Rudy Matela).
Then head over to Downloads and click the "Tags" tab and you'll get multiple options for download.
For the record, you can also toy around URLs this way :
When browsing the latest source, you have something like :
https://bitbucket.org/my/repo/src/latestcommithash/my.file?at=master
Simply change the commit hash and remove the GET parameter :
https://bitbucket.org/my/repo/src/wantedcommithash/my.file
Got to +1 #Hein A. Grønnestad above : it's all working, really wondering why there's nothing in the GUI to use it.
Add this to the end of any url: ?at=102beada4f1 (using the relevant commit SHA).
Note: the parameter is 'forgotten' with every new page load, so get ctrl + c and ctrl + v ready.
It's astonishing that BitBucket/Stash has no 'Browse files' button in the UI, like GitHub has:
Sigh.
You can view the source of the file up to a particular commit by appending
?until=<sha-of-commit> in the URL (after the file name).
The easiest way is to click on that commit and add a tag to that commit.
I have included the tag 'last_commit' with this commit
Than go to downloads in the left corner of the side nav in bit bucket.
Click on download in the left side
Now click on tags in the nav bar and download the zip from the UI.
Find your tag and download the zip
You can view it on your BitBucket web site
As explained on Atlassian community site, it's enough to go to the Source page (available from left side menu) and put your commit id in the at= query parameter of the url. So, for example, the url will end with ?at=bacf2ad3095.
I know it's too late, but with API 2.0 you can do
from command line with:
curl https://api.bitbucket.org/2.0/repositories/<user>/<repo>/filehistory/<branch>/<path_file>
or in php with:
$data = json_decode(file_get_contents("https://api.bitbucket.org/2.0/repositories/<user>/<repo>/filehistory/<branch>/<path_file>", true));
then you have the history of your file (from the most recent commit to the oldest one):
{
"pagelen": 50,
"values": [
{
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/<user>/<repo>/src/<hash>/<path_file>"
},
"meta": {
"href": "https://api.bitbucket.org/2.0/repositories/<user>/<repo>/src/<HEAD>/<path_file>?format=meta"
},
"history": {
"href": "https://api.bitbucket.org/2.0/repositories/<user>/<repo>/filehistory/<HEAD>/<path_file>"
}
},
"commit": {
"hash": "<HEAD>",
"type": "commit",
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/<user>/<repo>/commit/<HEAD>"
},
"html": {
"href": "https://bitbucket.org/<user>/<repo>/commits/<HEAD>"
}
}
},
"attributes": [],
"path": "<path_file>",
"type": "commit_file",
"size": 31
},
{
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/<user>/<repo>/src/<HEAD~1>/<path_file>"
},
"meta": {
"href": "https://api.bitbucket.org/2.0/repositories/<user>/<repo>/src/<HEAD~1>/<path_file>?format=meta"
},
"history": {
"href": "https://api.bitbucket.org/2.0/repositories/<user>/<repo>/filehistory/<HEAD~1>/<path_file>"
}
},
"commit": {
"hash": "<HEAD~1>",
"type": "commit",
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/<user>/<repo>/commit/<HEAD~1>"
},
"html": {
"href": "https://bitbucket.org/<user>/<repo>/commits/<HEAD~1>"
}
}
},
"attributes": [],
"path": "<path_file>",
"type": "commit_file",
"size": 20
}
],
"page": 1
}
where values > links > self provides the file at the moment in the history which you can retrieve it with curl <link> or file_get_contents(<link>).
Eventually, from the command line you can filter with:
curl https://api.bitbucket.org/2.0/repositories/<user>/<repo>/filehistory/<branch>/<path_file>?fields=values.links.self
in php, just make a foreach loop on the array $data.
Note: if <path_file> has a / you have to convert it in %2F.
See the doc here: https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Busername%7D/%7Brepo_slug%7D/filehistory/%7Bnode%7D/%7Bpath%7D
Search it for a long time, and finally, I found how to do it:)
Please check this image which illustrates steps.
In my case with Atlassian Bitbucket v6.10
https://<bitbucket.myserver.it>/projects/<myproject>/repos/<myrepo>/browse?at=<full-commit-hash>