# Welcome to your Stoplight workspace ## Getting Started This guide will help you design new API with reusable models and with a good versioning system ### Respect Naming Convention Once the project is created, the first thing to do is to remane the reference file. By default, in the reference folder you have one yaml file called .V1.yaml You have to rename this file so that Gitlab can diplay it properly. GitLab can render OpenAPI specification files with its file viewer, provided their filenames include openapi or swagger. The following examples are all correct: - .V1.openapi.yaml - .V1.swagger.yaml ### Handle API Versioning On the master branch, we put all the reference API of SBS by version (directly imported from the R&D without any modification). For each version, we create a new folder with the API version as a suffix Under the reference folder, each version of the reference API has a unique folder We cannot have any modification of the API in the master branch, for each modification of a reference API we need to create a new branch > ### Naming convention > New branch name must start with the prefix "release/" . > For example, if you want to design the V2 of an api, the branch should be named "release/v2" > After the branch is created, tell stoplight to track it so the versioning of the API is well display in the portal. Go to your project settings and click "+track branch", enter the name of the newly created branch and wait till it is imported > ### Displayed version > By default, the version name is the branch name but you can modified that in the settings of the project, just click on edit branch and then set the proper version name > When working in edit mode in one API, you can switch the branch your working on by clicking on the git branch icon located at the bottom left side of your screen. ### How to use a shared model across multiple projects > ### Commons model > Make sure a common Model project is already created containing all the versioned models of our organization > ### Commons model visibility > The common model project visibility must be public otherwise model export won't work. > In order to change visibility, just click on the project, then click share and set visibility to "Everyone" Once the models are created, they can be easyly browse via the explorer menu. There is a search form that you can use if you already know the model's name. > ### Watch Out! > > Model can also be vesionned so make sure you select the right version for your model before exporting it > Once you find the model you want, just click on it on then click on export -> original. It will open a new window. Just copy the url of the page and then go back to edit your API. To use the model, just click on "object" then click on "$ref", select "External URL" and in the form paste the copied url. If working corectly, you should be able to generate a example response by clicking on "+ Example" menu > ### A thing to know > > When using references in your API (meaning you don't create the model in the same project as your API), the generated openapi file will by default contain the reference and not the model itself (in the schema section of the openapi file) . If you want to generate an openapi file without any reference click on "export" and select the "Dereferenced" option ### How to use the embedded mock server Mocking in stoplight is pretty simple, just add some response example to your endpoint definition and the example will be automatically published on the Prism embedded mock server of stoplight. > ### Generate mock request and response is important > > According to stoplight best practices, it is recommended to always generate a example for both request and/or response To add a mock just click on example 1 and set the values in the json file. You can create multiples mock by clicking on example. Be sure to name your example with coherent name as the name of the mock can be important to the mock server To access the address of the published mocks, just go to the explorer window, select your endpoint and click on the mock button. It will give you an url to call for mocking. > ### Dynamic mocking > > It is possible to have different responses for a single operation, In that case the caller must specify the response name he want to retrieve by setting the header "Prefer" to the name of the example