Nswag Generate OpenApi Spec - asp.net-mvc

I have a number of controllers marked with different versioning, and marked with corresponding documentName. This works fine, I can then generate my OAS spec. Using the following and specifying the appropriate documentName
<Target Name="NSwag" AfterTargets="Build">
<Exec Command="$(NSwagExe_Core31) aspnetcore2openapi /project:$(AssemblyName).csproj /nobuild:true /documentName:v1 /output:OAS_v1.json" />
</Target>
However what would I do in a CI/CD system if I do not know what versions exist for given assembly? Think about a feed of assemblies that I go through to generate OAS files and distribute them to an API Management system.
Therefore is there a way that I can only create the version marked as default? Is there a way for me to know what documentName's exist so I can generate all of them?
Proposed Solution
I have not come up with an elegant idea - other than having an endpoint on the service that exposes the existing versions - and then use that to query the service or assembly to generate OAS files. Somebody have a better idea?

Related

How do you reuse the same openapi.yaml file for production and development

We are using a GitOps model for deploying our software. Everything in dev branch goes to the dev environment and everything in main gets deployed to production. All good and fine except that we use Google Cloud Endpoints that rely in the host parameter of the openapi.yaml. There is only room for a single value so we have to remember to change it for each deployment not allowing us to do a fully automated deploy.
How do you manage the same openapi.yaml definition when using Google Cloud Endpoints?
There is one example given in the official documentation, see if it helps your use-case.
Basic structure of an OpenAPI document, notice how the "host" is parameterized with "YOUR-PROJECT-ID.appspot.com"
Deploying the Endpoints configuration, using the provided script "./deploy_api.sh"
Source code for deploy_api.sh
One common solution for different environments properties management is to create different build profiles, and create different environment specific properties files like openapi_dev.yaml, openapi_qa.yaml, openapi_prod.yaml, and supply the one based on the profile(dev/qa/prod) being used. Refer here for more details.
Another way documented at GitOps-style continuous delivery with Cloud Build, where a multi branch, multi-repository approach is suggested.
Under the FAQ section in Swagger OpenAPI guide, it is clearly mentioned that, we can specify multiple hosts, e.g. development, test and production but for OpenAPI 3.0. OpenAPI2.0 supports only one host per API specification (or two if you count HTTP and HTTPS as different hosts). A possible way to target multiple hosts is to omit the host and schemes from your specification and serve it from each host. In this case, each copy of the specification will target the corresponding host.
As per Google documentation Cloud Endpoints currently support OpenAPI version 2.0. A feature request has been filed for support of version 3.0 but there have been no releases. You can follow for the updates here.

How does swagger-codegen automatically generate applications and dockerfiles?

I want to clarify the generation process of applications and dockerfiles. In order to understand this, I have drawn a graph to represent the flow based on my understanding of the documentation and source code. I will be glad if someone takes a look and corrects or approves the schema. The flow tries to describe the generation of NodeJS application from a Java application.
The swagger-codegen doesn't generate the template files, it uses the template files that are written by the (insert language here) codegen developer(s).
I assume the schema you've drawn is the flow of the NodeJSCodeGen because not every supported language generates a dockerfile.
Personally I would replace the Java microservice -> generates Model with OpenAPI specification -> Code Generator, as the generator uses the specification. It doesn't matter if you generated it from from a micro service or if you went with the API first approach.

Combine swagger Definition files

I am generating a swagger definition for all the my APIs by annotating the source code.
I was wondering if there is any way for make possible merge all the APIs in one single json file?
Note: I am using Swagger 2.0 definitions.
If you deploy those apps in a WebSphere Liberty server with the apiDiscovery-1.0 feature defined in your server.xml, then you can simply go into (GET) /ibm/api/docs and retrieve your aggregated JSON file. You can also retrieve it as YAML, by adding the Accept header "application/yaml".
You can download it for free at wasdev.net then just run the installUtility command to grab the feature (wlp/bin installUtility install apiDiscovery-1.0).
More information in this blog: https://developer.ibm.com/wasdev/blog/2016/04/13/deploying-swagger-enabled-endpoints-websphere-liberty-bluemix-api-connect/

Where is the appropriate place for SQL scripts in a Grails project

I've got a Grails plugin that exports domain objects so that several applications can share the same schema. We have a few SQL scripts for setting up some complex triggers, views and other functions that just don't really belong in GORM/Hibernate, at least not elegantly. I'd like to store the scripts inside the same project. Is the "scripts" folder (the one containing _[Un]Install/Upgrade.groovy) the best place for this? I saw a StackOverflow answer that was building a catalog from scripts stored in grails-app/conf/sql. But I'm not actually trying to execute them from within the a project.
The absolute best solution for anything database related is to use the database migration plugin. This way you can ensure that any database your application is pointed to (dev, test, prod, etc.) will have the same information/schema/functions/procedures etc.
Personal preference. I usually add a 'database' dir for all that kind of stuff. The 'scripts' dir is for Grails scripts, at least in 1.x and 2.x. See Creating Gant Scripts or the create-script command for more on those. In Grails 3 these kind of scripts have been moved to src/main/scripts.

Read param from web.xml in Ant build script

I want to be able to build my webapp in several variants, using as few configuration parameters as possible. I want to be able to just specify the folder in relation to the root of the URL into which i want it to deploy (that is, if i want it to be at http://example.com/one/, i want to specify just the word "one" in my config file).
I don't want to have several web.xml files or several build targets. Also, I know that it is not possible to modify web.xml by ant without using some external scripts. In this respect,
Is it possible to read a parameter from my web.xml file from an Ant script and then use the value in building?
You can read and modify any node/attribute from an XML file using XPath via the external xmltask :
http://www.oopsconsultancy.com/software/xmltask/, http://today.java.net/pub/a/today/2006/11/01/xml-manipulation-using-xmltask.html.
This widely-used ant task is very reliable.

Resources