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
- 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/
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