API fun

Rest lacked standards
https://dzone.com/articles/rest-api-documentation-part-1

in general an API has various “resources” that you access through “endpoints.” The endpoints give you access to the resource. (But terminology isn’t standard, so expect variety.
https://idratherbewriting.com/learnapidoc/docapis_resource_descriptions.html

The endpoints indicate how you access the resource, and the method used with the endpoint indicates the allowed interactions (such as GET, POST, or DELETE) with the resource...Path parameters (represent them through curly braces) are part of the endpoint itself, and are not optional.
https://idratherbewriting.com/learnapidoc/docapis_resource_endpoints.html


Parameters are options you can pass with the endpoint (such as specifying the response format or the amount returned) to influence the response. There are four types of parameters: header parameters, path parameters, query string parameters, and request body parameters
https://idratherbewriting.com/learnapidoc/docapis_doc_parameters.html

curl is a command-line utility that lets you execute HTTP requests with different parameters and methods. Instead of going to web resources in a browser’s address bar, you can use the command line to get these same resources, retrieved as text.
https://idratherbewriting.com/learnapidoc/docapis_install_curl.html


REST APIs follow an architectural style, not a specific standard. However, there are several REST specifications that have been developed to try to provide some standards about how REST APIs are described.
https://idratherbewriting.com/learnapidoc/pubapis_rest_specification_formats.html


With OpenAPI (Swagger), instead of XML, you have set of JSON objects, with a specific schema that defines their naming, order, and contents. This JSON file (often expressed in YAML instead of JSON) describes each part of your API. By describing your API in a standard format, publishing tools can programmatically ingest the information about your API and display each component in a stylized, interactive display.
https://idratherbewriting.com/learnapidoc/pubapis_swagger_intro.html

• https://github.com/OAI/OpenAPI-Specification

• Swagger HelloWorld Using Apigee API studio
• http://apistudio.io/727fcc47-f91a-4c3e-a9d0-a082a2090c01/#/

• Can use petstore apistudio by url:
• https://petstore.swagger.io/v2/swagger.yaml

Swagger editor
http://editor.swagger.io/

YAML refers to “YAML Ain’t Markup Language,”

https://swagger.io/tools/swagger-codegen/ is one of the code generators , but SmartBear who does SoapUI is supported.

display framework that reads an OpenAPI specification document and generates an interactive documentation website. This tutorial shows you how to use the Swagger UI interface and how to integrate an OpenAPI specification document into the standalone distribution of Swagger UI
https://idratherbewriting.com/learnapidoc/pubapis_swagger.html

• On Swagger Petstore page  click authorize.
• https://github.com/swagger-api/swagger-ui

The link for a good example
https://howtodoinjava.com/swagger2/swagger-spring-mvc-rest-example/

Or making a rest call using RestTemplate programatically:
https://spring.io/guides/gs/consuming-rest/

For example, I did this project example https://spring.io/guides/gs/rest-service/ and converted it to swaggerness and got json format with http://localhost:8080/v2/api-docs . Was able to get yaml with https://www.json2yaml.com/


Building a back-end API layer introduces a whole new area of challenges that goes beyond implementing just endpoints. You now have clients which will now be using your API. Your clients will need to know how to interact with your API. In SOAP-based web services, you had a WSDL to work with. This gave API developers an XML-based contract, which defined the API. However, with RESTFul web services, there is no WSDL. Thus your API documentation becomes more critical. API documentation should be structured so that it’s informative, succinct, and easy to read. But best practices on, how you document your API, its structure, what to include and what not to is altogether a different subject that I won’t be covering here"
https://dzone.com/articles/spring-boot-restful-api-documentation-with-swagger
https://www.infoq.com/presentations/doc-restful-api

API First Swagger Top Down approach

https://www.easyitblog.info/2017/01/08/api-first-approach-with-swagger/

"There are a lot of good API design tools. Here are some useful comcparisons"

• https://dzone.com/articles/rest-api-documentation-part-2-1
• http://modeling-languages.com/modeling-web-api-comparing/

need to add spec for API. How can we do this in Apigee, do we have option to create swagger documentation for REST service in Apigee or we have to use other tool to prepare documentation and create spec in Apigee by importing doc created using third party tool, if documentation is out of box solution in Apigee. If Api documentation possible in Apigee. Please share how to implement this.
https://community.apigee.com/questions/53011/rest-service-documentation.html

https://community.apigee.com/articles/25770/openapi-spec-swagger-spec-generator-a-tool-to-gene.html using SmartDocs The tool you can use is http://specgen.apistudio.io/


https://swagger.io/tools/

https://www.xoriant.com/blog/product-engineering/swagger-specification-code-generation.html