-
Using
- Importing Services & APIs
- Comparison to alternatives
- OpenAPI Mocking and Testing
- Swagger Mocking and Testing
- AsyncAPI Mocking and Testing
- Postman usage for Microcks
- gRPC Mocking and Testing
- GraphQL Mocking and Testing
- SoapUI Mocking and Testing
- Http Archive usage for Microcks
- Using exposed mocks
- Getting direct API
- Testing with Microcks
- Advanced topics
- Organizing repository
- Templating mock responses
- Dispatcher & dispatching rules
- Microcks APIMetadata
- Monitoring & Observability
- Installing
- Automating
- Administrating
- Guides
Microcks APIMetadata
🗓️ Last updated on September 28, 2021 | 3 | Improve this pageIntroduction
Some Microcks mocks specific metadata or properties cannot be fully deduced from common attributes coming from OpenAPI or AsyncAPI. Thus we should rely on default values can be later overwritten by manager
within Microcks either using the UI or through the Microcks API. That’s the reason why we introduced OpenAPI extensions
and AsyncAPI extensions
starting with Microcks 1.4.0
release.
But sometimes you don’t want to add some x-microcks
extensions attributes into AsyncAPI / OpenAPI document OR you’d need to specify these metadata and properties for some other artifact types like Protobuf
+ Postman collection
for GRPC mocking for instance 😉.
Hence we propose defining these metadata and properties into a standalone document called an APIMetadata
; document that can imported as a secondary
artifact thanks to the multi-artifacts support
now in Microcks.
For the later gRPC use-case, it means that the Defining dispatch rules step can be done automatically by importing another artifact that lives right next your files in Git repo.
APIMetadata format
Let start with an example! Here’s below an illustration of what could such an APIMetadata
document for one API. If you’re a reader of the Microcks Blog, you’ll notice this sample API with custom dispatching rules was introduced into the Advanced Dispatching and Constraints for mocks
post.
apiVersion: mocks.microcks.io/v1alpha1
kind: APIMetadata
metadata:
name: WeatherForecast API
version: 1.1.0
labels:
domain: weather
status: GA
team: Team C
operations:
'GET /forecast/{region}':
delay: 100
dispatcher: FALLBACK
dispatcherRules: |-
{
"dispatcher": "URI_PARTS",
"dispatcherRules": "region",
"fallback": "Unknown"
}
This example is pretty straightforward to understand and explain:
- This document is related to the
WeatherForecast API
in version1.1.0
. That means that this API version should already exist into your repository, otherwise the document will be ignored, - This document specifies additional
labels
used for organizing the Microcks repository . This labels will be added to existing ones, - This document specifies a default
delay
as well as custom dispatching informations for ourGET
operation. The name of operation should perfectly match the name of an existing operation - whether defined through OpenAPI, AsyncAPI, Postman Collection, SoapUI Project or Protobuf definition - otherwise it will be ignored.
Note that we can use multi-line notation in YAML but we will have to escape everything and put
\
before double-quotes and\n
characters if specified using JSON.
The semantic of those attributes are exactly the same that the one introduced into OpenAPI extensions and AsyncAPI extensions .
Importing APIMetadata specification
When you’re happy with your API Metadata just put the result YAML or JSON file into your favorite Source Configuration Management tool, grab the URL of the file corresponding to the branch you want to use and add it as a regular Job import into Microcks. On import, Microcks should detect that it’s an APIMetadata
specification file and choose the correct importer.
Using a Hello GRPC metadata
example here
, you should get the following screen. Do not forget to tick the Secondary Artifact checkbox!
Still Didn’t Find Your Answer?
Join our community and get the help you need. Engage with other members, ask questions, and share knowledge to resolve your queries and expand your understanding.
Join the community