Google Git
Sign in
apache / servicecomb-website / refs/heads/asf-site / . / content / docs / users / service-contract / index.html
blob: fa76522ddc8ae08fe106e1b1922eb9ff2bc2566b [file] [log] [blame]
<!doctype html>
<!--
Minimal Mistakes Jekyll Theme 4.4.1 by Michael Rose
Copyright 2017 Michael Rose - mademistakes.com | @mmistakes
Free for personal and commercial use under the MIT license
https://github.com/mmistakes/minimal-mistakes/blob/master/LICENSE.txt
-->
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<!-- begin SEO -->
<title>Service Contract - Apache ServiceComb</title>
<meta name="description" content="Service Contract">
<meta name="author" content="">
<meta property="og:locale" content="en">
<meta property="og:site_name" content="Apache ServiceComb">
<meta property="og:title" content="Service Contract">
<link rel="canonical" href="https://github.com/pages/apache/incubator-servicecomb-website/docs/users/service-contract/">
<meta property="og:url" content="https://github.com/pages/apache/incubator-servicecomb-website/docs/users/service-contract/">
<meta property="og:description" content="Service Contract">
<meta name="twitter:site" content="@ServiceComb">
<meta name="twitter:title" content="Service Contract">
<meta name="twitter:description" content="Service Contract">
<meta name="twitter:url" content="">
<meta name="twitter:card" content="summary">
<script type="application/ld+json">
{
"@context" : "http://schema.org",
"@type" : "Person",
"name" : "Apache ServiceComb",
"url" : "https://github.com/pages/apache/incubator-servicecomb-website",
"sameAs" : null
}
</script>
<meta name="google-site-verification" content="HvJjNd7vvJ-yjSTHlBiIWEYxp_Hrz-PYEY5Idz9LRcA" />
<!-- end SEO -->
<link href="/feed.xml" type="application/atom+xml" rel="alternate" title="Apache ServiceComb Feed">
<!-- http://t.co/dKP3o1e -->
<meta name="HandheldFriendly" content="True">
<meta name="MobileOptimized" content="320">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script>
document.documentElement.className = document.documentElement.className.replace(/\bno-js\b/g, '') + ' js ';
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js"></script>
<script src="/assets/vendor/prism/prism.js"></script>
<script type="text/javascript" async
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML">
</script>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta/css/bootstrap.min.css" integrity="sha384-/Y6pD6FV/Vv2HJnA6t+vslU6fwYXjCFtcEpHbNJ0lyAFsXTsjBbfaDjzALeQsN6M" crossorigin="anonymous">
<script src="https://www.apachecon.com/event-images/snippet.js"></script>
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.11.0/umd/popper.min.js" integrity="sha384-b/U6ypiBEHpOf/4+1nzFpr53nxSS+GLCkfwBdFNTxtclqqenISfwAzpKaMNFNmj4" crossorigin="anonymous"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta/js/bootstrap.min.js" integrity="sha384-h0AbiXch4ZDo7tp9hKZ4TsHbi047NrKGLO3SEJAg45jXxnGIfYzk4Si90RDIqNm1" crossorigin="anonymous"></script>
<!-- For all browsers -->
<link rel="stylesheet" href="/assets/css/main.css">
<link rel="stylesheet" href="/assets/vendor/prism/prism.css">
<!--[if lte IE 9]>
<style>
/* old IE unsupported flexbox fixes */
.greedy-nav .site-title {
padding-right: 3em;
}
.greedy-nav button {
position: absolute;
top: 0;
right: 0;
height: 100%;
}
</style>
<![endif]-->
<meta http-equiv="cleartype" content="on">
<!-- start custom head snippets -->
<!-- insert favicons. use http://realfavicongenerator.net/ -->
<link href="https://fonts.loli.net/css?family=Roboto:400,500,700|Source+Code+Pro" rel="stylesheet">
<script src="/assets/js/custom.js"></script>
<!-- end custom head snippets -->
</head>
<body class="layout--single">
<!--[if lt IE 9]>
<div class="notice--danger align-center" style="margin: 0;">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> to improve your experience.</div>
<![endif]-->
<div class="masthead" onmouseleave="$('#childrenShow').css('display', 'none')">
<div class="masthead__inner-wrap">
<div class="masthead__menu">
<nav id="site-nav" class="greedy-nav">
<a class="site-title active" href="/"><img src="https://www.apache.org/img/servicecomb.png"></a>
<ul class="visible-links">
<li class="masthead__menu-item" onmouseenter="$('#childrenShow').css('display', 'none')">
<a href="/">Home</a>
</li>
<li class="masthead__menu-item" onmouseenter="$('#childrenShow').css('display', 'none')">
<a href="/developers/">Projects</a>
</li>
<li class="def-nav-li" onmouseenter="$('#childrenShow').css('display', 'block')">
<a class="active" href="/docs/users/">Documentation</a>
<ul id="childrenShow" class="def-children-show-en" onmouseleave="$('#childrenShow').css('display', 'none')">
<li><a href="/docs/getting-started/" class="">Getting started</a></li>
<li><a href="/docs/users/" class="">Docs</a></li>
<li><a href="/slides/" class="">Video</a></li>
<li><a href="/faqs/" class="">FAQ</a></li>
</ul>
</li>
<li class="masthead__menu-item" onmouseenter="$('#childrenShow').css('display', 'none')">
<a href="/year-archive/">Blogs</a>
</li>
<li class="masthead__menu-item" onmouseenter="$('#childrenShow').css('display', 'none')">
<a href="/release/">Downloads</a>
</li>
</ul>
<button><div class="navicon"></div></button>
<ul class="hidden-links hidden"></ul>
<div class="nav-lang">
<a href=/cn/docs/users/service-contract/>中文</a>
</div>
</nav>
</div>
</div>
</div>
<div id="main" role="main">
<div class="sidebar sticky">
<div class="back-to-home"><a href="/">Home</a> > Service Contract</div>
<nav class="nav__list">
<input id="ac-toc" name="accordion-toc" type="checkbox" />
<label for="ac-toc">Toggle Menu</label>
<ul class="nav__items">
<li>
<span class="nav__sub-title">Java Chassis User Guide</span>
<ul>
<li><a href="/references/java-chassis/zh_CN/index.html" class="">Java Chassis 3</a></li>
<li><a href="/references/java-chassis/2.x/zh_CN/index.html" class="">Java Chassis 2</a></li>
</ul>
</li>
<li>
<span class="nav__sub-title">Pack User Guide</span>
<ul>
<li><a href="https://github.com/apache/servicecomb-pack/blob/master/docs/user_guide.md" class="">0.5.0</a></li>
</ul>
</li>
<li>
<span class="nav__sub-title">ServiceCenter User Guide</span>
<ul>
<li><a href="https://service-center.readthedocs.io/en/latest/user-guides.html" class="">2.0.0</a></li>
</ul>
</li>
<li>
<span class="nav__sub-title">Kie User Guide</span>
<ul>
<li><a href="https://kie.readthedocs.io/en/latest/" class="">0.2.0</a></li>
</ul>
</li>
<li>
<span class="nav__sub-title">Mesher User Guide</span>
<ul>
<li><a href="https://mesher.readthedocs.io/en/latest/" class="">1.6.3</a></li>
</ul>
</li>
</ul>
</nav>
</div>
<article class="page" itemscope itemtype="http://schema.org/CreativeWork">
<meta itemprop="headline" content="Service Contract">
<meta itemprop="description" content="Service Contract">
<meta itemprop="dateModified" content="August 15, 2017">
<div class="page__inner-wrap">
<header>
<h1 class="page__title" itemprop="headline">Service Contract
</h1>
</header>
<section class="page__content" itemprop="text">
<aside class="sidebar__right">
<nav class="toc">
<!-- <header><h4 class="nav__title"><i class="fa fa-file-text"></i> On This Page</h4></header> -->
<ul class="toc__menu" id="markdown-toc">
<li><a href="#concept-description" id="markdown-toc-concept-description">Concept Description</a></li>
<li><a href="#scenario" id="markdown-toc-scenario">Scenario</a></li>
<li><a href="#explicit-api-definition" id="markdown-toc-explicit-api-definition">Explicit API Definition</a> <ul>
<li><a href="#configuration" id="markdown-toc-configuration">Configuration</a></li>
<li><a href="#sample-code" id="markdown-toc-sample-code">Sample Code</a></li>
</ul>
</li>
<li><a href="#implicit-api-definition" id="markdown-toc-implicit-api-definition">Implicit API Definition</a> <ul>
<li><a href="#concept-description-1" id="markdown-toc-concept-description-1">Concept Description</a></li>
<li><a href="#scenario-1" id="markdown-toc-scenario-1">Scenario</a></li>
<li><a href="#involved-api" id="markdown-toc-involved-api">Involved API</a></li>
</ul>
</li>
</ul>
</nav>
</aside>
<h2 id="concept-description">Concept Description</h2>
<p>The API of provider and consumer microservice is defined based on OpenAPI regulations.</p>
<h2 id="scenario">Scenario</h2>
<p>The API definition decouples providers and consumers, which allows the two parties to use different programming languages, Providers provide services and consumers call them based on the API definition.</p>
<h2 id="explicit-api-definition">Explicit API Definition</h2>
<h3 id="configuration">Configuration</h3>
<p>ServiceComb defines API in a .yaml file. You are advised to use <a href="http://editor.swagger.io/#/">Swagger Editor</a> to write an API definition. This tool can check syntax and automaticlly generate an API document. For details about the API definition file format, see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md"> Official OpenAPI documentation</a>。</p>
<p>The API definition file is located in “resources/microservices” or “resources/applications” directory. The directory structure is as follows:</p>
<pre><code class="language-txt">resources
- microservices
- serviceName #Microservice name
- schemaId.yaml #schema API definition
- applications
- appId #Application ID
- serviceName #Service name
- schemaId.yaml #Schema API definition
</code></pre>
<h3 id="sample-code">Sample Code</h3>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">swagger</span><span class="pi">:</span> <span class="s1">'</span><span class="s">2.0'</span>
<span class="na">info</span><span class="pi">:</span>
<span class="na">title</span><span class="pi">:</span> <span class="s">hello</span>
<span class="na">version</span><span class="pi">:</span> <span class="s">1.0.0</span>
<span class="na">x-java-interface</span><span class="pi">:</span> <span class="s">org.apache.servicecomb.samples.common.schema.Hello</span>
<span class="na">basePath</span><span class="pi">:</span> <span class="s">/springmvchello</span>
<span class="na">produces</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">application/json</span>
<span class="na">paths</span><span class="pi">:</span>
<span class="s">/sayhi</span><span class="pi">:</span>
<span class="na">post</span><span class="pi">:</span>
<span class="na">operationId</span><span class="pi">:</span> <span class="s">sayHi</span>
<span class="na">parameters</span><span class="pi">:</span>
<span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">name</span>
<span class="na">in</span><span class="pi">:</span> <span class="s">query</span>
<span class="na">required</span><span class="pi">:</span> <span class="no">true</span>
<span class="na">type</span><span class="pi">:</span> <span class="s">string</span>
<span class="na">responses</span><span class="pi">:</span>
<span class="na">200</span><span class="pi">:</span>
<span class="na">description</span><span class="pi">:</span> <span class="s">returned for a correct result</span>
<span class="na">schema</span><span class="pi">:</span>
<span class="na">type</span><span class="pi">:</span> <span class="s">string</span>
<span class="na">default</span><span class="pi">:</span>
<span class="na">description</span><span class="pi">:</span> <span class="s">returned for a default result</span>
<span class="na">schema</span><span class="pi">:</span>
<span class="na">type</span><span class="pi">:</span> <span class="s">string</span>
<span class="s">/sayhello</span><span class="pi">:</span>
<span class="na">post</span><span class="pi">:</span>
<span class="na">operationId</span><span class="pi">:</span> <span class="s">sayHello</span>
<span class="na">parameters</span><span class="pi">:</span>
<span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">person</span>
<span class="na">in</span><span class="pi">:</span> <span class="s">body</span>
<span class="na">required</span><span class="pi">:</span> <span class="no">true</span>
<span class="na">schema</span><span class="pi">:</span>
<span class="s">$ref</span><span class="pi">:</span> <span class="s2">"</span><span class="s">#/definitions/Person"</span>
<span class="na">responses</span><span class="pi">:</span>
<span class="na">200</span><span class="pi">:</span>
<span class="na">description</span><span class="pi">:</span> <span class="s">returned for a correct result</span>
<span class="na">schema</span><span class="pi">:</span>
<span class="na">type</span><span class="pi">:</span> <span class="s">string</span>
<span class="na">default</span><span class="pi">:</span>
<span class="na">description</span><span class="pi">:</span> <span class="s">returned for a default result</span>
<span class="na">schema</span><span class="pi">:</span>
<span class="na">type</span><span class="pi">:</span> <span class="s">string</span>
<span class="na">definitions</span><span class="pi">:</span>
<span class="na">Person</span><span class="pi">:</span>
<span class="na">type</span><span class="pi">:</span> <span class="s2">"</span><span class="s">object"</span>
<span class="na">properties</span><span class="pi">:</span>
<span class="na">name</span><span class="pi">:</span>
<span class="na">type</span><span class="pi">:</span> <span class="s2">"</span><span class="s">string"</span>
<span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">person</span><span class="nv"> </span><span class="s">name"</span>
<span class="na">xml</span><span class="pi">:</span>
<span class="na">name</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Person"</span>
</code></pre></div></div>
<blockquote>
<p><strong>NOTE</strong>：</p>
<ul>
<li>According to Swagger specifications, the path specified by basePath should contain the webroot of the web server.</li>
<li>info.x-java-interface requires a specific API path. Set it as needed.</li>
</ul>
</blockquote>
<h2 id="implicit-api-definition">Implicit API Definition</h2>
<h3 id="concept-description-1">Concept Description</h3>
<p>　　The inplicit API definition is automatically generated by ServiceComb based on the service implementation class.</p>
<h3 id="scenario-1">Scenario</h3>
<p>　　By using the implicit API definition you can define the implementation class without pre-defining APIs. When the service is started, an API is automatically generated and registered to the service center.</p>
<h3 id="involved-api">Involved API</h3>
<p>　　Implicit API definitions can be used for Spring MVC, JAX-RS, and transparent RPC development modes, For details, see <a href="/users/develop-with-springmvc/">Development Style-SpringMVC</a>, <a href="/users/develop-with-jax-rs/">Development Stype-JAX-RS</a> and <a href="/users/develop-with-transparent-rpc/">Development Style-Transparent RPC</a>.</p>
<p>　　When you develop a microservice in transparent RPC mode, the code does not show how you want to define an API, and all generated APIs are POST methods, The input parameters of all the methods will be packaged as a class and transferred as body parameters. Therefore, if you develop providers using implicit APIs, you are advised to choose Spring MVC or JAX-RS mode to obtain complete RESTful statements.</p>
</section>
<footer class="page__meta">
</footer>
</div>
</article>
</div>
<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<div align="center" style="margin: 0 0;">
<ins class="adsbygoogle"
style="display:block; border-bottom: initial;"
data-ad-client="ca-pub-7328585512091257"
data-ad-slot="3049671934"
data-ad-format="auto"></ins>
</div>
<div class="page__footer">
<footer>
<!-- start custom footer snippets -->
<!-- end custom footer snippets -->
<div class="container">
<div class="row justify-content-md-center">
<div class="col">
<ul>
<p class="header">Events</p>
<a class="acevent" data-format="square" data-mode="dark" data-event="random"></a>
</ul>
</div>
<div class="col">
<ul>
<p class="header">Resources</p>
<li><a href="/docs/getting-started/">Getting started</a></li>
<li><a href="/docs/users/">User Guide</a></li>
<li><a href="/slides/">Slides</a></li>
<li><a href="/users/faq/">Common Questions</a></li>
</ul>
</div>
<div class="col">
<ul>
<p class="header">ASF</p>
<li><a href="http://www.apache.org">Foundation</a></li>
<li><a href="http://www.apache.org/licenses/">License</a></li>
<li><a href="http://www.apache.org/events/current-event">Events</a></li>
<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
</ul>
</div>
<div class="col">
<ul>
<p class="header">Contribute</p>
<li><a href="http://issues.apache.org/jira/browse/SCB">Report a Doc Issue</a></li>
<li><a href="https://github.com/apache/servicecomb-website/edit/master/_users/define-service-contract.md">Edit This Page on Github</a></li>
<li><a href="/developers/submit-codes/">Code Submit Guide</a></li>
<li><a href="/security">Security</a></li>
</ul>
</div>
<div class="col">
<ul class="social-icons">
<p class="header">Community</p>
<li>
<a href="mailto:dev-subscribe@servicecomb.incubator.apache.org" rel="nofollow"><span class="mail">Mailing List</span></a>
</li>
<li>
<a href="https://github.com/apache?q=ServiceComb" target="_blank"><span class="github">Github</span></a>
</li>
<li>
<a href="https://twitter.com/ServiceComb" target="_blank"><span class="twitter">Twitter</span></a>
</li>
<li>
<a href="/feed.xml" target="_blank"><span class="rss">Feed</span></a>
</li>
</ul>
</div>
</div>
</div>
<div class="page__footer-bottom">
<div>&copy; 2024 Apache ServiceComb. Powered by <a href="http://jekyllrb.com" rel="nofollow">Jekyll</a> &amp; <a href="https://mademistakes.com/work/minimal-mistakes-jekyll-theme/" rel="nofollow">Minimal Mistakes</a>.</div>
<div>All other marks mentioned may be trademarks or registered trademarks of their respective owners.</div>
</div>
</footer>
</div>
<script src="/assets/js/main.min.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-101622733-1', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>