I'm new to the OpenAPI 3.0.0.
I have successfully created a java client library using an openapi-generator.
But OpenAPI Generator allows the generation of API client libraries (SDK generation), server stubs, documentation. So I want to know is there any commands or steps are available to generate HTML documentation and also to customize the documentation template.
Old question, but for those still bumping into it. OpenApi Generator can do generation of html documentation from your yaml or json definition of your API.
openapi-generator generate -i PathToMyInputDefinitionFile.yaml -g html -o /PathToOutputFolder
Where html is the generator you want to use. Other generators include dynamic-html and html2. Also can emit as markdown. See https://openapi-generator.tech/docs/generators/
If using Docker, a full example would look like this:
docker run --rm -v ${PWD}:/local openapitools/openapi-generator:tagname generate -i /local/input.yaml -g html -o /local
PWD is present working directory (current directory) in the host, which you are mapping on to /local in the container. Adjust 'tagname' to suit, from https://hub.docker.com/r/openapitools/openapi-generator/tags Adjust input.yaml to be your input file yaml definition of your API.
Related
I'm trying to use the Kube OpenAPI tool openapi-gen to generate OpenAPI specs for Google's Config Connector.
I'm relatively new to Go, so I'm not sure whether this is a configuration error on my part or if I'm simply using it wrong.
I've cloned the Kube OpenAPI repo, and inside of that directory I've cloned the Config Connector repo, for simplicity.
This is what's happening when I try to generate an OpenAPI spec file.
$ go run cmd/openapi-gen/openapi-gen.go -i ./k8s-config-connector/pkg/apis/serviceusage/v1beta1 -p foo.com/foo -h ./boilerplate/boilerplate.go.txt
E0811 16:45:57.516697 22683 openapi.go:309] Error when generating: TypeMeta, TypeMeta invalid type
2021/08/11 16:45:57 OpenAPI code generation error: Failed executing generator: some packages had errors:
failed to generate default in ./k8s-config-connector/pkg/apis/serviceusage/v1beta1.Service: TypeMeta: not sure how to enforce default for Unsupported
exit status 1
What's going on here?
Here are some troubleshooting steps:
1 - GOROOT variable should be set and point to root of go installation
2- Operator-sdk depended on it being exported as an environment variable. Run the below command
export GOROOT=$(go env GOROOT)
when using the operator-sdk, it is necessary to either (a) set GOROOT in your environment, or (b) use the same GOROOT that was used to build the operator-sdk binary.
Refer to the link for additional information.
I am currently writing a third-party client for a website, but it doesn't expose interface, so I try to crawl datas by myself. The website uses GraphQL, so I use apollo-android in my project, By reading README.md of apollo-CLI, I still have trouble in generating schema.json file.
Could you tell me the detailed steps of how to generate schema.json?
For schema.json you should have apollo-codegen which is used to send an introspection query to server and get schema.json.
For getting apollo-codegen execute following from the command-prompt to install it:
npm install apollo-codegen -g
For sending the introspection query and getting the schema.json execute following:
apollo-codegen download-schema https://api.github.com/graphql --output schema.json
Replace https://api.github.com/graphql with your link
You can then find the schema.json file saved to the folder from where you ran the above commands.
Source
apollo-codegen had meanwhile be replaced with apollo:
The 'apollo-codegen' command has been replaced with the more-powerful 'apollo' CLI. Switch to 'apollo' to ensure future updates and visit https://npm.im/apollo#code-generation for more information.
So this would be:
sudo npm install apollo -g
And it's options:
$ apollo client:download-schema --help
Download a schema from Apollo or a GraphQL endpoint in JSON or SDL format
USAGE
$ apollo client:download-schema OUTPUT
ARGUMENTS
OUTPUT [default: schema.json] Path to write the introspection result to. Can be `.graphql`, `.gql`, `.graphqls`, or `.json`
OPTIONS
-c, --config=config Path to your Apollo config file
-g, --graph=graph The ID for the graph in Apollo to operate client commands with. Overrides config file if set.
-v, --variant=variant The variant of the graph in Apollo to associate this client to
--clientName=clientName Name of the client that the queries will be attached to
--clientReferenceId=clientReferenceId Reference id for the client which will match ids from client traces, will use clientName if not provided
--clientVersion=clientVersion The version of the client that the queries will be attached to
--endpoint=endpoint The URL for the CLI use to introspect your service
--excludes=excludes Glob of files to exclude for GraphQL operations. Caveat: this doesn't currently work in watch mode
--header=header Additional header to send during introspection. May be used multiple times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED if using the `--header` flag.
--includes=includes Glob of files to search for GraphQL operations. This should be used to find queries *and* any client schema extensions
--key=key The API key to use for authentication to Apollo
--queries=queries Deprecated in favor of the includes flag
--tagName=tagName Name of the template literal tag used to identify template literals containing GraphQL
queries in Javascript/Typescript code
For example:
apollo client:download-schema --endpoint=https://api.github.com/graphql schema.json
Can flatbuffer be used for server client communication?Previously i was using JSON, but do you think flatbuffer will be useful for communication where the response from server is big enough to create some delay in reaching the client side.
If flatbuffer is not recommended, then which one I can use?Is there any library that can reduce the size of response from server and send it to client side for efficient and fast communication?
One of the best way to learn how to use flatbuffer and also to know more about flatbuffers vs JSON. (How to use FlatBuffers?)
FlatBuffer Android Sample Application
This app shows how fast flat buffer works when we compare it with json.
How to start with flatBuffer
$ git clone https://github.com/google/flatbuffers.git
$ cd flatbuffers
* Run the command on the basis of your platform
$ cmake -G "Unix Makefiles"
$ cmake -G "Visual Studio 10"
$ cmake -G "Xcode"
* now build for your platform as usual. This should result in a flatc executable
* Now create your schema file with extension .fbs. Guide to write a schema can be found [here]("https://google.github.io/flatbuffers/flatbuffers_guide_writing_schema.html").And also have your sample json file.
$ ./flatc -j -b schema.fbs sample.json
* This will create few java file and one bin file. Java files are like model(POJO for flatBuffer) of your json.Place the java files in your application package and bin file in raw folder(bin file is only for testing as it is converted to byte that is to be passed to flatbuffer for testing).
* Now we have to get flatbuffer jar file.
$ cd flatbuffers
$ cd java
$ mvn install
This will download all the dependencies.
$ cd target
* Here we will get the flatbuffers-java-1.3.0-SNAPSHOT.jar file that we have to put it in your libs folder of android project.
* For rest you can see my (https://github.com/amitshekhariitbhu/FlatBuffer).
## Major steps:
* Prepare your schema.fbs.
* Have a sample json.
* Build flatBuffer google project to generate your java files to be used in main application.
* Generate java files.
Yes, a FlatBuffers message will typically be a lot smaller than the equivalent JSON, and it will be quicker to access.
I have just started playing with google proto. When I try to compile proto file present in proto-java example, it does not generate any grpc file.
proto file,
https://github.com/grpc/grpc-java/blob/master/examples/src/main/proto/hello_world.proto
terminal output,
rsonkhla#raman-OptiPlex-9020:~/sandbox/grpc-java/examples$ protoc
--version libprotoc 3.0.0 rsonkhla#raman-OptiPlex-9020:~/sandbox/grpc-java/examples$ protoc
--java_out=test/ -I../../grpc-java/examples ../../grpc-java/examples/src/main/proto/hello_world.proto
rsonkhla#raman-OptiPlex-9020:~/sandbox/grpc-java/examples$ ls -R test/
test/: io
test/io: grpc
test/io/grpc: examples
test/io/grpc/examples: helloworld
test/io/grpc/examples/helloworld: HelloRequest.java
HelloResponse.java HelloWorldProto.java
HelloRequestOrBuilder.java HelloResponseOrBuilder.java
Has anybody else faced this issue?
The command line you are showing does not enable the grpc plugin. You need to specify an _out argument for the grpc plugin, which enables the plugin and specifies where it should output files. Since the plugin is likely not in your PATH, you also need to tell protoc how to find the plugin with --plugin.
So you need to add two arguments:
--plugin=protoc-gen-grpc-java=path/to/protoc-gen-grpc-java --grpc-java_out=path/to/output/dir
For more info, see the gRPC compiler documentation.
You can add these option to your .proto (base on your language) to generate abstract services:
option cc_generic_services = true;
option java_generic_services = true;
option py_generic_services = true;
You can also add --plugin=EXECUTABLE option in your protoc cmd to use custom code generator plugin to generate code more specific to each system, rather than rely on the "abstract" services. Just like Eric's suggestion.
I am trying to build a tr069 client using gsoap. I followed the instructions in the document but I could not get soapClient.c.
Here is the steps:
wsdl2h -c -o tr069.h cwmp-1-1.xsd --> this generate tr069.h
soapcpp2 -c tr069.h --> this only generates the following file:
ns1.nsmap, soapC.c soapH.h soapStub.h
According to the examples online and in the document, I am suppose to get file like soapClient.c
Does anyone knows why? I am using gsoap 2.8
Thanks.
The cwmp-1-1.xsd is only an XSD file. You do not have a WSDL defining the operations that normally are stored in soapClient.c. However, you can still use the XML root element serializers (see bottom part of tr069.h for instructions) over sockets etc.