Notes about Swagger

swagger.md

Swagger

• https://swagger.io/
• It belongs to SmartBear (SoapUI creators)
• Swager 2.x = OpenAPI 3.x
• Open Source tools
  • Swagger Editor
  • Swagger UI
  • Swagger Codegen
• SwaggerHub:
  • https://swagger.io/tools/swaggerhub/pricing/
  • Free, Team and Enterprise plans
  • Free: you can not use the collaboration. It offers API Editor, hosted documentation and API mocking. Only public.
  • Team: 75$/month for 5 users, 150$/month for 10 users.
  • Enterprise: from 25 users up.

Swagger Editor

• https://swagger.io/tools/swagger-editor/
• For solo developers
• Design, describe and document your API
• Live Demo: https://editor.swagger.io/?_ga=2.219833689.11271560.1537128182-1999993717.1536953559
• You can either download it or use Swagger Hub
• Notes after trying it:
  • You can run it dockerized
  • You can import a YAML/JSon OAS spec
  • You can export a YAML/JSon OAS spec
  • You can generate a server from it (in many different languages/libraries)
  • You can generate a client from it (for many different languages/libraries)
    • It include some tests (without assertions).
  • Doubts/problems
    • Downloading the jaxrs and starting it, it doesn't work (maybe problems related with Spotify artifactory because of jett?).
    • Worked the spring server, then accessible through:
      • http://localhost:8080/v2
      • http://localhost:8080/v2/api-docs
      • curl -X GET --header 'Accept: application/json' 'http://localhost:8080/v2/store/inventory'
    • Java client:
      • The basePath is an optional parameter (it should be a mandatory parameter in the constructor, if the client forgets to change it, it would go against the Swagger Petstore).

Swagger UI

• https://swagger.io/tools/swagger-ui/
• Just for visualizing and interacting, NOT for designing.
• You can run a Dockerized version: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md
• You can use a URI for the OAS JSon file, or include it when running Docker
• I guess it's not for sharing the documentation, but just to visualize it and interact. You can tell your clients about its existence... what else?
• Doubts
  • Is it possible to integrate it in the CI/CD pipeline and publish it?

Swagger Inspector

• https://swagger.io/tools/swagger-inspector/
• https://inspector.swagger.io/builder?_ga=2.173332004.625114735.1540470449-287074697.1540208031
• Test and document APIs without testing your patience.
• Looks like a Postman alternative. You can save your tests and create curations.
• You introduce the URI, and then click on "Create API Definition": it creates the documentation on your Swagger Hub account.
• Then, from Swagger Hub, you can again generate a client, a stub server, generate documentation, etc.

Swagger codegen

• https://swagger.io/tools/swagger-codegen/
• Build and enable consumption of your API by generating server stubs and client SDKs with minimal plumbing.
• You can download it: https://github.com/swagger-api/swagger-codegen
• Generate server stubs: https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO
• Generate client SDKs
• Generate documentation

Swagger Hub

• https://swagger.io/tools/swaggerhub/
• Swagger Hub Enterprise: https://swagger.io/tools/swaggerhub/enterprise/
• API design and documentation with OpenAPI
• API Mocking.
• For teams. Free and Pro versions.
• Definitions and documentation are hosted on SwaggerHub, the API design and documentation platform for teams.
• Looks like you can create an organization (e.g. CSAT) and share access... (not sure)
  • You can share/invite to specific users (with an email).

More stuff

• Swagger validator badge: https://github.com/swagger-api/validator-badge
• Swagger test templates: https://www.npmjs.com/package/swagger-test-templates
• Mock data generator: https://github.com/subeeshcbabu/swagmock
• OpenAPI Java annotations:
  • Looks like you can generate the OAS from Java annotations. That could be another approach: you can do BDD and the implementation of the server/provider/endpoint would generate the OAS (more similar to Pact approach, CDC).
  • https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations
  • https://github.com/swagger-api/swagger-core
  • https://github.com/swagger-api/swagger-samples

OpenAPI specification

• https://swagger.io/specification/
• https://en.wikipedia.org/wiki/OpenAPI_Specification
• The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
• Features
  • Authentication support
  • Support for callbacks
  • Increased examples
• Version 2.0 vs 3.0
  • v3.0: https://swagger.io/blog/news/announcing-openapi-3-0/
  • https://swagger.io/blog/news/whats-new-in-openapi-3-0/
  • https://swagger.io/docs/specification/basic-structure/
  • Last released version [25.10.2018]: 3.0.2
  • version, info, servers, paths (relative path, verb, parameters, request body, responses), components/schemas (the types), security

To be read

• https://swagger.io/swagger/media/blog/wp-content/uploads/2017/02/Documenting-An-Existing-API-with-Swagger-2.pdf

Doubts

• Test generation?
• Lots of overlapping... ?
• Prices for SwaggerHub Pro