The latest version might not be compatible with this tutorial. Provide a few basic pieces of information to the swaggerDefinition, such as the title and version of your API; you can fill in more later. For example,./swagger/v1/swagger.json. app.UseSwaggerUI(c => What Is the Difference Between Swagger and OpenAPI. You can use this parameter to set a different validator URL, for example for locally deployed validators (Validator Badge). (Pay attention to last slash: ui/), Try use this tutorial: * description: The user's name. I was successful. * name: * allOf: You'll see a section called Request body with the schema you've provided: You might have noticed you've repeated the user schema several times in the documentation so far. When I now configure the App URL settings in the project properties to start at http://localhost:50000/swagger the browser opens and shows the wrong url, namely http://localhost:50000/swagger/api/values with the correct response of the ValuesController but not the swagger ui. Second, the comments can be compiled later into a complete set of reference documentation. * properties: Thanks to everyone for the work around. For more information on the basic structure of the OpenAPI Specification, see Basic Structure. 참고로 앞으로 볼 모든 코드는 Github 에서 확인할 수 있다. * type: object } This tutorial uses the following API-related terms and definitions defined by OpenAPI: The full URL used to retrieve data from the API is formed by adding the endpoint to the base URL: localhost:3000/users. Use a colon (:) or curly brackets ({}) to mark a path parameter in the endpoint path. * application/json: But in my idea there is something to fix. * User: * example: 0 Then, add an endpoint path called /docs (or any name of your choosing): As shown above, swagger-ui-express provides two callbacks to set up the endpoint: one to set up Swagger UI with the swaggerSpec definitions and one to serve it to the /docs endpoint. JSDoc is a popular tool for generating documentation from comments in the source code of your app. * description: Created * responses: Hence it is very important for them to understand how to use our API effectively. The second project is about integrating Swagger using JSDoc comments throughout your code. * schema: "launchUrl": "api/values", Swagger library is useful if you are creating REST services in spring boot web application. I too updated VS and..bam....no more swagger. * requestBody: * post: The goal is to enable the service producer to update the service documentation in real time so that client (consumer) can get up-to-date information about the service structure … Generate server stubs and client SDKs from OpenAPI Specification definitions . The full URL used to retrieve data from the API is formed by adding the endpoint to the base URL: localhost:3000/users. Restart the Express server, and navigate again to localhost:3000/docs in the browser. * type: string Use the Host Name or IP address of the computer where Swagger is running. * application/json: Successfully merging a pull request may close this issue. "applicationUrl": "http://localhost:51565/" Port 8008 is hosting the Swagger-UI, and port 8100 is hosting the actual API. This example shows that name can be sent in the request body. You should see a listing for GET /users near the bottom of the page: Your users will want to know what is returned when this GET request is successful (i.e., with a status code of 200). * requestBody: Had same issue, the swagger/swagger fix works, but is not good. "environmentVariables": { * properties: The API documentation is the process of giving instructions about how to effectively use and integrate an API. Made with love and Ruby on Rails. Use the Host Name or IP address of the computer where Swagger is running. * description: Retrieve a single JSONPlaceholder user. * type: object Should now work as … * name: Then copy and paste the swagger… * type: object You can continue adding path definitions for the remaining routes in the same way. You can add more properties for new users later. * description: A single user. To create a Swagger UI page for your Express API, include swagger-ui-express in the app.js file. You won't need to specify the path definitions here, since each path is defined separately in a JSDoc comment (to be added in the next step). * - type: object // Paths to files containing OpenAPI definitions. You can then write JSDoc comments in your API's source code to generate the OpenAPI definitions. "launchBrowser": true, If you want more practice with the OpenAPI Specification, you can finish documenting the jsonplaceholder-express-api. Also see the swagger-jsdoc CLI docs. Thanks for all the tips on this page. In the OpenAPI docs, you'll notice there's also a paths field. You'll see a list of parameters for this route: Next, document the request body for POST /users to describe the data required to create a new user in the database. As this tutorial will show, these definitions can be written in YAML directly in JSDoc comments. follow this guide. But first, you should add more root definitions for the API. Echo positions itself as a high performance and minimalist web framework. Deleting the .vs folder worked for me too, you must deploy .Net Core application to IIS. Open.vs/config/applicationhost.config and remove all application entries with the '/swagger' path on your site. Swagger is a specification for documenting REST API. With a Swagger UI docs page available at the /docs endpoint and a complete set of root information on your API, you can start writing your path definitions. By clicking “Sign up for GitHub”, you agree to our terms of service and * get: * summary: Create a JSONPlaceholder user. Swagger가 적용된 화면 * type: string The # symbol indicates the root of the current document, and the remaining nested values are then resolved in order. message: You now have the start of a beautiful docs page for your API! * example: 0 Seems to work fine at this step. Mine was a simple delete of the .vs folder. * $ref: '#/components/schemas/User' What makes frontend so miserable for backend developers? Return to app.js. * example: Leanne Graham * post: These file paths should be relative to the root directory of your Express API. Swagger or OpenAPI describes the standards and specifications for the RESTFul API description.These specifications are an attempt to create a universal and language agnostic description for describing the REST API. { In our case, JSONPlaceholder returns an object with a data field, which contains the data you've requested. Thank toi, I will look forward tous afternoon :). Read more about types in the Data Types documentation. * parameters: * type: string }. The description should provide more detail, such as when or why you would want to use the route. Firing end points at this step seems to work but with strange 500.19 for somes. Oh okay, I think I found a way to generate an HTML file. Accessinglocalhost:port/swagger/ui without slash at the end will result redirecting to swagger/swagger/ui/ and 404 error. To create a Swagger UI page from JSDoc comments, you’ll need a way to pass your documentation to Swagger UI: To install swagger-jsdoc and swagger-ui-express to your Express API, run. * description: The user's name. For what it's worth I can reproduce this consistently now by setting the app url to /swagger/ in the project build settings. It retrieves user data from JSONPlaceholder. Nothing in configuration have changed only upgrade to VS2017 15.5.1. i currently use swagger for api documentation and swagger ui as test harness. * @swagger This is a REST API application made with Express. * responses: No other changes were made and I use Visual Studio 2017. I couldn't get /swagger to work (would always kick to /swagger/swagger, but I was able to get api/docs to work with the following config: It may be worth noting that /swagger was working fine for me, even after updating visual studio. Setting it to either none, 127.0.0.1 or localhost will disable validation. * get: First, the documentation is directly available to anyone viewing the source code. }); * application/json: I feel like I have tried everything. * required: true * 200: */. If using directories with IIS or a reverse proxy, set the Swagger endpoint to a relative path using the./ prefix. * ... Was anyone able to fix it or has any workaround? Swagger was appending the route to the end of your application path, if your application path is set as localhost:53250/swagger for example, then the swagger application will be {appUrl}/swagger which in this case would be localhost:53250/swagger/swagger. If I now enter (without stopping the app) http://localhost:50000/swagger I start receiving 404 errors an urls, even on http://localhost:50000/api/values. There are three main components to Swashbuckle: Swashbuckle.AspNetCore.Swagger: a Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints.. Swashbuckle.AspNetCore.SwaggerGen: a Swagger … * @swagger At this step no breakpoint in the debug are active and app is not stopping anymore on any breakpoints. In your Express API's app.js file, add the following code below the list of required modules: The swaggerDefinition object (i.e., the OpenAPI definition) defines the root information for your API. I tried all what is possible around RoutePrefix and at the end UI shows with cascading 3 /swagger : http://localhost:50000/swagger/swagger/swagger !!!!! It can also recognize JSR-303 annotations, so you'll have also documented all the constraints on your model classes. Guys this helped me. we found an issue in spring boot … This tutorial has also covered the basics of writing OpenAPI definitions. Updated the value and viola swagger was back. * description: The user ID. To see a version of the jsonplaceholder-express-api that includes all the code added during this tutorial, see the repository's docs branch. * @swagger * description: The user ID. The issues is with appliacationhost.config after changing project properties > debug > App url. You'll see your NewUser schema in the request body definition for POST /users: This covers the basic techniques for producing OpenAPI definitions in JSDoc comments. See Basic Structure for more information on the other properties you can add to the root definition. Once again, all the Swagger documentation is written in this fashion, and be warned: spacing/indentation and colons do matter. The Swagger-UI looks correct in the browser, and when I test a simple get method, it shows the request URL properly. And yet I followed different tutorials and I created 5 test projects. View or download sample code (how to download). I just installed Swashbuckle.AspNetCore 3.0.0. To define a successful response, add a responses object and a response called 200 to the path definition: The description field describes the response or what it returns. This is helpful since you do not need to use Postman or some other tool to test REST Apis. * ... Enabling Swagger In Your .NET Core 2.0 Application - A Step By Step Guide. Can be used to populate a list of fake users when prototyping or testing an API. * type: object I lost a full day of trying to debug. * example: 0 Given how developer-friendly Visual Studio is, I'm … This is where API documentation comes into the picture. We'll do some refactoring in a later step. You should see the response, an example value (using the example values you provided for each property), and the schema for the data returned in this response: Next, define the GET /users/:id path by adding the fields we've covered already (summary, description, and responses): The path parameter (id) is added to the endpoint path: /users/:id. * content: In this tutorial, you will set up a Swagger UI documentation web page for an Express API. "sslPort": 0 You can now reference NewUser from the request body definition for POST /users: Restart the Express server, and navigate again to localhost:3000/docs in the browser. * description: The user's name. "launchUrl": "swagger", It can also utilize core swagger classes such as … * name: * components: Change the application URL back to your default path without '/swagger'. * responses: You should see more information about your API at the top of the docs page: You can now start documenting your Express routes. * type: object * example: Leanne Graham You'll see the title and version number of your Express API, as well as the OpenAPI version number (3.0.0). * required: true * /users/:id: This is pretty useful, especially when you have … * name: Remember about '/' in path. Follow this with some basic information about the route: Note that swagger-jsdoc looks for comments with a @swagger or @openapi tag to create OpenAPI definitions. to your account. Let me know if this works for you! * items: Add 'swagger' to the 'Launch Browser' property (right click project, properties -> Debug). "launchBrowser": true, See Describing Request Body for more details. Can be used to populate a user profile when prototyping or testing an API. * properties: https://neelbhatt.com/2018/01/30/deploy-net-core-application-to-iis-step-by-step-guide/ * id: Sample project to demonstrate OpenAPI Swagger configuration in Guice grizzly jersey example. I'm not really familiar with Swagger Codegen, but I found this wrapper: swagger-nodegen-cli. I have just updated VS to 15.9.3 and Swagger stopped working showing 404. Next, define POST /users by adding the fields we've covered already (summary, description, and responses): A successful response in this case would be 201. This serves two purposes. * schemas: In swagger 2.4.0 this is still a bug. // force to add another /swagger to fix issue If you use Confluence to distribute your documentation, you could create a new file inside Confluence and choose to add OpenAPI Specification. DEV Community © 2016 - 2020. When doing this the swagger ui needs to be allowed to access the REST resources across the origin (CORS). }); Albeit not the perfect scenario, but got me back to coding. It is possible to generate the documentation into a static html page to be readeable without launching the server ? * responses: To document parameters, add a parameters field to the path definition: In the definition for this parameter, in defines the parameter's location (in this case, it's a path parameter because it's part of the path). * example: Leanne Graham API editor for designing APIs with the OpenAPI Specification. * components: Using /swagger/v1/swagger.json instructs the app to look for the JSON file at the true root of the URL (plus the route prefix, if used). It looks like Rolf's answer is the way to go. * description: The user's name. * properties: /** * 201: If you wish to change the URL that your browser is directed to, when starting your new asp.net project you need to change your launch settings. * type: object Since we have no other definitions yet, you'll see a "No operations defined in spec!" It retrieves data from JSONPlaceholder. * description: A list of users. * type: string * post: Can be used to populate a user profile when prototyping or testing an API. * example: Leanne Graham Restart the Express server, and navigate again to localhost:3000/docs in the browser. * description: The user ID. We are going to write a small hello world maven application containing one REST api endpoint and will generate OpenAPI swagger documentation for it. c.SwaggerEndpoint("/swagger/swagger/v1/swagger.json", "My API V1"); The strange thing is that the problem persists even if I change the app url back to root unless I also delete the .vs folder per sebastianpec. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making … * description: Retrieve a list of users from JSONPlaceholder. The issue is that you need to add / to the end of the url. You have just to create a new virtual directory with a new port number for the webApi Application after you have installed and configured Swagger on it. Each path definition corresponds to an Express route in your API. Hence it can be thought of as a concise reference manual containi… Good luck :), I seen that what he shared is for a maven project and I try to find for an express project :(. I'm having the same problem with version 4.0.1 and VS2019. * description: Retrieve a single JSONPlaceholder user. Notice how the types are defined in this schema. To make things work, add / at the end of swagger url: * type: object I'll look into this and get back to you, No problem. * get: * id: The Swagger Editor, Swagger UI, and Swagger Codegen are free and open-source tools while Swagger Hub is free for one user and paid for organization and teams. * @swagger * get: Navigate to either of these to see user data from JSONPlaceholder. c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); I had error with swagger/swagger/swagger so I assumed that it is because IIS express configuration file :). */, /** You can also describe error responses this way. Swagger UI creates a web page from OpenAPI Specification definitions. Swagger Codegen. It describes both the operation and endpoint path, such as GET /users and DELETE /users/:id. "IIS Express": { * description: The user's name. http://localhost:50000/swagger/api/values, http://localhost:50000/swagger/swagger/swagger, http://localhost:50000/swagger/swagger/swagger/swagger, 2.0.0 Relative SwaggerEndpoint URL doesn't work, No webpage was found for the web address: http://localhost:29435/swagger/, https://neelbhatt.com/2018/01/30/deploy-net-core-application-to-iis-step-by-step-guide/, Enabling Swagger In Your .NET Core 2.0 Application - A Step By Step Guide. With you every step of your journey. To create a Swagger UI page from JSDoc comments, you’ll need a way to pass your documentation to Swagger … You've created a basic set of OpenAPI definitions and a Swagger UI page that displays them. "iisSettings": { Add Swagger to the Project. Echo is one of the most popular frameworks for Go. 在swagger ui的页面上有: Base URL: 如果没有特别设定,那么显示的就是服务器的地址。接口的测试的url是由Base URL +接口的path。 一般情况下是没有问题的。但是我这边代码部署到服务器后,访问地址变成了 :服务器的地址+项目name,这样的话,base Url显示其实就有问题了,少了项目name。 It wasn't until I edited my launchsettings.json file for the first time that this problem cropped up. * 200: There's another way of doing this with tools provided by Swagger.io you can have it load in the OpenAPI yaml document, and it will generate the HTML specification document for you. "environmentVariables": { */, /** As per Greg post 👍 here is a FUNCTIONAL launchSettings.json, { * responses: We're a place where coders share, stay up-to-date and grow their careers. * name: swagger.yaml => The Swagger Specification in yaml file format. * @swagger I was able to access the documentation via http://localhost:58030/swagger Then I removed the ValuesController (default controller in the VS template) and updated the LaunchUrl in launchSettings.json. The Swagger.json file swagger: "2.0" info: version: "0.0.1" title: tistory test # swagger가 실행되고 있는 host를 설정해 줍니다. It’s simple to use. Sign up for a free GitHub account to open an issue and contact its maintainers and the community. Reverting the changes did not fix the issue. Add a real example value for each property (e.g., 'Leanne Graham'); otherwise, Swagger UI creates a generic example such as 'string'. * description: The user ID. * schema: Swagger. Swagger Inspector is for testing the APIs endpoints in the cloud and it is paid. localhost:port/swagger/ui/ The REST endpoints exposed by the Remedy AR System Server are documented by using Swagger specifications. This is not because VisualStudio but IIS Express. }, I had the same problem, Delete vs folder and it is working again. Since then I have this same issue. * example: 0 DEV Community – A constructive and inclusive social network for software developers. Hope this gets fixed in next version. Swagger for the Iris web framework. its not recommended to serve up static web content from API. * description: Retrieve a list of users from JSONPlaceholder. You'll pass this object to Swagger UI in the next step. * type: string swagger : http://localhost:8080/swagger/index.html springboot中的swagger:http://localhost:8080/swagger App stpp on breakpoint as before. VS also saves each and every application path you enter, so if you had once entered the path with a /swagger route, it will still be saved in the .config and hence each time you try to go to {app}/swagger it is going to the apps route, not to the route with /swagger appended. You can list the filenames individually or use the wildcard delimiter * to add all JavaScript files in a directory, as shown above. To document /routes/users.js, first add a comment starting with @swagger above the first route. I was also experiencing this issue. after some time some endpoins on swagger UI disappears, even though they still work when called externally. If you have multiple versions of your api, you can … You can also add a name, description, and schema and whether the parameter is required. * example: 0 } See Swagger's Describing Responses documentation for more details on the fields available for describing each response. 프로젝트에서 지정한 URL들을 HTML화면으로 확인할 수 있게 해주는 프로젝트이다 of your Express API used this... Is the Difference Between Swagger and OpenAPI = > the Swagger docs spec... Forward tous afternoon: ) or curly brackets ( { } ) to mark a path parameter in the.. * 200: * 200: * description: the user 's.. Our API effectively the process of giving instructions about how to effectively use and integrate an API can the! Comments throughout your code be relative to the Swagger Specification in a directory, as well newly... N'T collect excess data, as shown in the browser to mark a path parameter the... Goal of this route ( CORS ) can install the Express server, and navigate again to localhost:3000/docs in source. Documentation is … use Localhost in the /routes files to anyone viewing the source code the... Have also documented all the code added during this tutorial can now start documenting your routes! A colon (: ) or curly brackets ( { } ) to mark a path in... Community – a constructive and inclusive social network for software developers chrome return ERR_CONNECTION_REFUSED and I... Then resolved in order these path definitions are compiled by swagger-jsdoc into a complete set reference! Is about integrating Swagger using JSDoc comments in your API your app nothing! Tutorials and I use Visual Studio: you can view the endpoints provided this... It can be used to populate a user profile when prototyping or testing API! Sample code ( how to use two spaces ( or four spaces for! With version 4.0.1 and VS2019 only upgrade to VS2017 15.5.1, FabianGosebrink/ASPNETCore-WebAPI-Sample 1! Up static web content from API brackets ( { } ) to mark a path parameter the... Swagger.Json or swagger.yaml file normally used by swagger-jsdoc to produce swagger localhost url complete set of OpenAPI definitions with SB and! Produce a complete reference documentation I edited my launchsettings.json file for the routes! Finish documenting the jsonplaceholder-express-api a new file inside Confluence and choose to OpenAPI... Pass this object to Swagger UI creates a docs page, and navigate again localhost:3000/docs. Software developers popular frameworks for Go then moves to /swagger/swagger and API calls to /swagger/ 수 있게 해주는 프로젝트이다 file! Project properties > debug > app URL contains this swaggerDefinition object and an array of paths called apis recommended! The set of reference documentation Host name or IP address of the jsonplaceholder-express-api to add all files. From JSONPlaceholder followed different tutorials and I created 5 test projects your model classes seems work. You use Confluence to distribute your documentation, you can finish documenting the jsonplaceholder-express-api see Declarative comments format test! Allof, not for more information on the fields available for Describing response... Start writing docs navigate to either none, 127.0.0.1 or Localhost will disable validation: a single.... Way to generate the documentation is written in YAML directly in JSDoc directly in JSDoc directly in the debug active... And I created 5 test projects afternoon: ) now by setting the app ) http: //localhost:50000/swagger/swagger!!... Can automatically generate Swagger documentation is written in YAML directly in the repository docs. From a set of OpenAPI definitions and swagger-ui-express as requested at # 1231.. Usage start using.... 'Ll pass this object to Swagger swagger localhost url page for an Express API can be used to a! Port/Swagger 404 error and execute get, post, PUT, DELETE vs folder and loads. Spring boot … Swagger for API documentation with Swagger 2.0 as requested at # 1231.. start! Happened after I moved my project to demonstrate OpenAPI swagger localhost url documentation is directly available anyone! Path definitions are compiled by swagger-jsdoc to produce a complete reference documentation and get. Operations defined in spec! writer, open source advocate, developer 's. Install Swagger editor and Swagger UI page for your Express API then write JSDoc throughout. That name can be used to populate a list of fake users when prototyping or an. Express routes new user each path definition: this adds a request body ( 2.0 ) apis. Suddenly stopped working after upgrading Visual Studio see user data from JSONPlaceholder you to view REST services spring. # swagger가 실행되고 있는 host를 설정해 줍니다 object with a data field, which the... Properties you can try out operations and see results using sample data complete your documentation you! Vs to 15.9.3 and Swagger UI to access the REST resources across the origin ( CORS ) Specification! { } ) to swagger localhost url this duplication, you should add more properties for users. Firing end points at this stage, check that your swagger-jsdoc version is 5.0.1.. A variable called swaggerSpec thank toi, I happened after I moved project. In Guice grizzly jersey example then resolved in order very important for them to understand to. Try running sc version to make sure it was n't until I edited launchsettings.json! I 'll look into this and get back to your default path without '/swagger ' path on your controller! 실행되고 있는 host를 설정해 줍니다 frameworks for Go Swagger stopped working after upgrading Studio. Web application is displayed in the end point documentation page for your Express API, as well the... Just updated vs to 15.9.3 and Swagger UI API can be used to populate a list of users and! Generated request URL into another browser window and it loads the response … add Swagger the! 'S source code, see Declarative comments format could create a new file inside Confluence and to! Issue, the documentation into a static html page to be readeable without launching the server back to your path! The bwagent REST API, where you can define the user 's name swagger.io ’ s online validator can the... The redirect URL > debug ), consult the OpenAPI Specification in YAML or json to describe web. Time that this problem cropped up all JavaScript files in a later step or four spaces.. But with issue about swagger.json of course appliacationhost.config after changing project properties > debug.! Terms of service and privacy statement are now set up a Swagger to! Set to start writing docs provides a basic set of OpenAPI definitions static web content from API should more... Disable validation response, data contains an array of paths called apis see Swagger 's Describing responses documentation for.! Remember about '/ ' in path add a requestBody field to this path definition to. Schema in one place and reference it from elsewhere Swagger library is if... Again to localhost:3000/docs in the data types documentation application URL back to,! 사용할 basePath를 설정해 줍니다 you could create a new file inside Confluence and choose to add / to root! Model classes tistory test # swagger가 실행되고 있는 host를 설정해 줍니다 at the top of the Specification, the... Ui needs to be rebuilt 15.5.1 or VS2017 15.5.1 or VS2017 15.5.1 or VS2017 15.5.1 or VS2017 15.5.1 VS2017... Correct in the cloud and it loads the response object latest version might not be compatible this. Point documentation page for your Express API can be used to populate a user profile when prototyping or an... Warned: spacing/indentation and colons do matter and execute get, post, can. And model classes because it’s not clear to me get /users/: id and if so what to... Swagger UI creates a docs page for your Express API, as shown in the endpoint to the build! The base URL: localhost:3000/users add the endpoint path, such as when or why would! About how to download ) object contains this swaggerDefinition object and an array, add endpoint... The combobox.Url is the name of the Specification, you can now start documenting Express... Anyone viewing the source code of your app as this tutorial has also covered the of. Describe a REST API, as shown above SwaggerUI then moves to /swagger/swagger API... Refactoring in a variable called swaggerSpec complete set of OpenAPI definitions /users/: id [ /swagger/v1/swagger.json ] but does... Issue is that you need to use Postman or some other tool test... Okay, I happened after I moved my project to demonstrate OpenAPI Swagger in! To serve up static web content from API of this tutorial populate a user when! Requested at # 1231.. Usage start using it populate a list of JSONPlaceholder users just or! Generate server stubs and client SDKs from OpenAPI Specification and the schema describes response. After upgrading Visual Studio 2017 json ) is fine this documentation: swagger localhost url page. Response object was working fine developing.NET Core ( 2.0 ) web apis after. ( CORS ) all application entries with the OpenAPI version number of your API. Localhost in the data you 've created a basic introduction to OpenAPI definitions I lost a full day of to. Added during this tutorial can be used to Retrieve data from JSONPlaceholder: version: `` 2.0 '' info version. You now have the same problem with version 4.0.1 and VS2019 any breakpoints spaces ) for indentation not... Anyone able to fix it or has any workaround define an array of user objects spring controller and model.! Have just updated vs and.. bam.... no more Swagger this an issue contact... Not for more details 프로젝트에서 지정한 URL들을 HTML화면으로 확인할 수 있게 해주는 프로젝트이다 에서. Is useful if you want more practice with the OpenAPI version number of your Express API used this... Field containing the new user Swagger using JSDoc comments directly available to viewing. Just one or two user properties ( e.g., id and name ) to describe REST web..