一.REST
REST并非是一种技术或者规范，而是一种架构风格
rest风格风格的url
http://192.168.139.1/project/user/1
常用的HTTP Meshod对应含义
| 方式 | 含义 |
|---|---|
| POST | 代表增加资源 |
| PUT | 代表修改资源 |
| GET | 代表获取资源 |
| DELETE | 代表删除资源 |
SpringBoot默认集成REST
在SpringBoot中
- @PostMapping
- @PutMapping
- @GetMapping
- @DeleteMapping
分别对应上述四种请求方法
二.Swagger
使用Swagger步骤：
1.下载Swagger-ui
https://github.com/swagger-api/swagger-ui/releases
下载Swagger UI 3.17.4，然后解压
2.选择解压后的dist文件夹，在SpringBoot项目下 static文件夹下新建一个Swagger3文件夹，将里面的所有文件拷贝到Swagger3下
3.测试
启动SpringBoot应用
访问 http://localhost:8080/swagger3/index.html
见到下面，代表成功
定制Swagger
Swagger2.0规范
官方文档
https://swagger.io/docs/specification/2-0/basic-structure/
https://swagger.io/specification/v2/
基本属性：
| 属性 | 含义 |
|---|---|
| swagger | 代表swagger规范，固定为2.0 |
| info | 代表一个项目基本信息 |
| basePath | 代表根目录，例如：http://localhost:8080/v1/swagger3/index.html下的/v1 |
| paths | 代表访问路径 |
| tags | 标签表示当前访问路径归于哪一组 |
| summary | 接口主要功能的简单描述 |
| description | 接口的详细描述 |
| parameters | 接口的参数 |
| responses | 响应状态码 |
| consumes | 定义支持的MIME类型 |
| definitions | 定义使用的公共数据结构 |
查询参数描述
例如：/xxxx/xxxxx?id=123
"parameters":[
{
"name":"id", //代表参数名
"in":"query",
"description":"根据id查询",
"required":true
}
],URL中的参数
例如：/xxxx/xxxx/{id}
"parameters":[
{
"name":"id",
"in":"path",
"description":"hello id",
"required":true
}
],表单参数
"parameters":[
{
"name":"id",
"in":"formData",
"description":"hello id",
"required":true
}
],文件上传参数
"parameters":[
{
"name":"id",
"in":"formData",
"description":"hello id",
"type":"file"
}
],整个请求体作为参数
"parameters":[
{
"name":"user",
"in":"body",
"description":"hello user",
"required":true,
"schema":{
"$ref":"#definitions/user"
}
}
],完整例子：
配置文件application
# 设置默认路径
server.servlet.context-path=/v1HelloController
@Controller
public class HelloController {
/**
* 根据id获取user
* @param id
* @return
*/
@GetMapping("/user/{id}")
@ResponseBody
public User getUser(@PathVariable String id){
User user = new User();
user.setId(id);
user.setName("zhangsan");
user.setAge(1);
user.setPhone("123456");
user.setHobby("basketball");
System.out.println(user);
return user;
}
/**
* 获取user
* @return
*/
@GetMapping("/user")
@ResponseBody
public User getUsers(){
User user = new User();
user.setId("123456");
user.setName("lisi");
user.setAge(1);
user.setPhone("123456");
user.setHobby("basketball");
System.out.println(user);
return user;
}
/**
* 获取user
* @return
*/
@GetMapping("/users")
@ResponseBody
public List<User> getAllUsers(){
List<User> list = new ArrayList<>();
for (int i = 0; i < 5; i++) {
User user = new User();
user.setId("1xxx" + i);
user.setName("lisi" + i);
user.setAge(1);
user.setPhone("123456");
user.setHobby("basketball");
list.add(user);
}
return list;
}
/**
* 获取msg
* @param id
* @return
*/
@RequestMapping("/msg/{id}")
@ResponseBody
public Map<String,String> getMsg(@PathVariable Integer id){
Map<String,String> map = new HashMap<>();
map.put("msg","Hello " + id);
return map;
}
/**
* 获取上传的user
* @param user
* @return
*/
@RequestMapping("/uploadUser")
@ResponseBody
public User findUser(@RequestBody User user){
System.out.println(user);
return user;
}
}
sample.json
{
"swagger":"2.0",
"info":{
"description":"这是一个Swagger项目简单的实例",
"version":"1.0",
"title":"Swagger Demo"
},
"basePath":"/v1",
"paths":{
"/msg/{id}":{
"get":{
"tags":[
"msg"
],
"summary":"获取id信息",
"consumes":[
"application/json",
"application/xml"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"hello id",
"required":true,
}
],
"responses":{
"200": { "description":"获取id成功" } }
}
},
"/user/{id}":{
"get":{
"tags":[
"user"
],
"summary":"获取id信息",
"consumes":[
"application/json",
"application/xml"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"hello id",
"required":true }
],
"responses":{
"200": { "description":"根据id获取user成功" } }
}
},
"/user":{
"get":{
"tags":[
"user"
],
"summary":"获取id信息",
"consumes":[
"application/json",
"application/xml"
],
"responses":{
"200": { "description":"获取User成功" } }
}
},
"/users":{
"get":{
"tags":[
"user"
],
"summary":"获取id信息",
"consumes":[
"application/json",
"application/xml"
],
"responses":{
"200": { "description":"获取User成功" } }
}
},
"/uploadUser":{
"post":{
"tags":[
"user"
],
"summary":"上传user",
"consumes":[
"application/json",
"application/xml"
],
"parameters":[
{
"name":"user",
"in":"body",
"description":"hello user",
"required":true,
"schema":{ "$ref":"#definitions/user" } }
],
"responses":{
"200": { "description":"获取id成功" } }
}
},
},
"definitions":{
"user": {
"type": "object",
"properties": {
"id": {
"type": "string" },
"name": {
"type": "string" },
"age": {
"type": "integer" },
"phone": {
"type": "string" },
"hobby": {
"type": "string" }
}
},
"other": {
"type": "object",
"properties": {
"msg": {
"type": "string" }
}
}
}
}将swagger3/index.html内的url替换为访问自己编写的sample.json地址
访问：
http://localhost:8080/v1/swagger3/index.html
可见：
测试msg
测试获取users
使用整个请求体作为参数
默认的 https://petstore.swagger.io/v2/swagger.json
可以根据官方提供的模板模仿定制
{
"swagger": "2.0",
"info": {
"description": "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.",
"version": "1.0.0",
"title": "Swagger Petstore",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"email": "[email protected]"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"host": "petstore.swagger.io",
"basePath": "/v2",
"tags": [
{
"name": "pet",
"description": "Everything about your Pets",
"externalDocs": {
"description": "Find out more",
"url": "http://swagger.io"
}
},
{
"name": "store",
"description": "Access to Petstore orders"
},
{
"name": "user",
"description": "Operations about user",
"externalDocs": {
"description": "Find out more about our store",
"url": "http://swagger.io"
}
}
],
"schemes": [
"https",
"http"
],
"paths": {
"/pet": {
"post": {
"tags": [
"pet"
],
"summary": "Add a new pet to the store",
"description": "",
"operationId": "addPet",
"consumes": [
"application/json",
"application/xml"
],
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "Pet object that needs to be added to the store",
"required": true,
"schema": { "$ref": "#/definitions/Pet" } }
],
"responses": {
"405": { "description": "Invalid input" } },
"security": [
{
"petstore_auth": [ "write:pets", "read:pets" ] }
]
},
"put": {
"tags": [
"pet"
],
"summary": "Update an existing pet",
"description": "",
"operationId": "updatePet",
"consumes": [
"application/json",
"application/xml"
],
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "Pet object that needs to be added to the store",
"required": true,
"schema": { "$ref": "#/definitions/Pet" } }
],
"responses": {
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Pet not found" },
"405": { "description": "Validation exception" } },
"security": [
{
"petstore_auth": [ "write:pets", "read:pets" ] }
]
}
},
"/pet/findByStatus": {
"get": {
"tags": [
"pet"
],
"summary": "Finds Pets by status",
"description": "Multiple status values can be provided with comma separated strings",
"operationId": "findPetsByStatus",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "status",
"in": "query",
"description": "Status values that need to be considered for filter",
"required": true,
"type": "array",
"items": { "type": "string", "enum": [ "available", "pending", "sold" ], "default": "available" },
"collectionFormat": "multi" }
],
"responses": {
"200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } } },
"400": { "description": "Invalid status value" } },
"security": [
{
"petstore_auth": [ "write:pets", "read:pets" ] }
]
}
},
"/pet/findByTags": {
"get": {
"tags": [
"pet"
],
"summary": "Finds Pets by tags",
"description": "Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.",
"operationId": "findPetsByTags",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "tags",
"in": "query",
"description": "Tags to filter by",
"required": true,
"type": "array",
"items": { "type": "string" },
"collectionFormat": "multi" }
],
"responses": {
"200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } } },
"400": { "description": "Invalid tag value" } },
"security": [
{
"petstore_auth": [ "write:pets", "read:pets" ] }
],
"deprecated": true
}
},
"/pet/{petId}": {
"get": {
"tags": [
"pet"
],
"summary": "Find pet by ID",
"description": "Returns a single pet",
"operationId": "getPetById",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet to return",
"required": true,
"type": "integer",
"format": "int64" }
],
"responses": {
"200": { "description": "successful operation", "schema": { "$ref": "#/definitions/Pet" } },
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Pet not found" } },
"security": [
{
"api_key": [] }
]
},
"post": {
"tags": [
"pet"
],
"summary": "Updates a pet in the store with form data",
"description": "",
"operationId": "updatePetWithForm",
"consumes": [
"application/x-www-form-urlencoded"
],
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet that needs to be updated",
"required": true,
"type": "integer",
"format": "int64" },
{
"name": "name",
"in": "formData",
"description": "Updated name of the pet",
"required": false,
"type": "string" },
{
"name": "status",
"in": "formData",
"description": "Updated status of the pet",
"required": false,
"type": "string" }
],
"responses": {
"405": { "description": "Invalid input" } },
"security": [
{
"petstore_auth": [ "write:pets", "read:pets" ] }
]
},
"delete": {
"tags": [
"pet"
],
"summary": "Deletes a pet",
"description": "",
"operationId": "deletePet",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "api_key",
"in": "header",
"required": false,
"type": "string" },
{
"name": "petId",
"in": "path",
"description": "Pet id to delete",
"required": true,
"type": "integer",
"format": "int64" }
],
"responses": {
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Pet not found" } },
"security": [
{
"petstore_auth": [ "write:pets", "read:pets" ] }
]
}
},
"/pet/{petId}/uploadImage": {
"post": {
"tags": [
"pet"
],
"summary": "uploads an image",
"description": "",
"operationId": "uploadFile",
"consumes": [
"multipart/form-data"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet to update",
"required": true,
"type": "integer",
"format": "int64" },
{
"name": "additionalMetadata",
"in": "formData",
"description": "Additional data to pass to server",
"required": false,
"type": "string" },
{
"name": "file",
"in": "formData",
"description": "file to upload",
"required": false,
"type": "file" }
],
"responses": {
"200": { "description": "successful operation", "schema": { "$ref": "#/definitions/ApiResponse" } } },
"security": [
{
"petstore_auth": [ "write:pets", "read:pets" ] }
]
}
},
"/store/inventory": {
"get": {
"tags": [
"store"
],
"summary": "Returns pet inventories by status",
"description": "Returns a map of status codes to quantities",
"operationId": "getInventory",
"produces": [
"application/json"
],
"parameters": [],
"responses": {
"200": { "description": "successful operation", "schema": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } },
"security": [
{
"api_key": [] }
]
}
},
"/store/order": {
"post": {
"tags": [
"store"
],
"summary": "Place an order for a pet",
"description": "",
"operationId": "placeOrder",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "order placed for purchasing the pet",
"required": true,
"schema": { "$ref": "#/definitions/Order" } }
],
"responses": {
"200": { "description": "successful operation", "schema": { "$ref": "#/definitions/Order" } },
"400": { "description": "Invalid Order" } }
}
},
"/store/order/{orderId}": {
"get": {
"tags": [
"store"
],
"summary": "Find purchase order by ID",
"description": "For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions",
"operationId": "getOrderById",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "orderId",
"in": "path",
"description": "ID of pet that needs to be fetched",
"required": true,
"type": "integer",
"maximum": 10.0,
"minimum": 1.0,
"format": "int64" }
],
"responses": {
"200": { "description": "successful operation", "schema": { "$ref": "#/definitions/Order" } },
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Order not found" } }
},
"delete": {
"tags": [
"store"
],
"summary": "Delete purchase order by ID",
"description": "For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors",
"operationId": "deleteOrder",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "orderId",
"in": "path",
"description": "ID of the order that needs to be deleted",
"required": true,
"type": "integer",
"minimum": 1.0,
"format": "int64" }
],
"responses": {
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Order not found" } }
}
},
"/user": {
"post": {
"tags": [
"user"
],
"summary": "Create user",
"description": "This can only be done by the logged in user.",
"operationId": "createUser",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "Created user object",
"required": true,
"schema": { "$ref": "#/definitions/User" } }
],
"responses": {
"default": { "description": "successful operation" } }
}
},
"/user/createWithArray": {
"post": {
"tags": [
"user"
],
"summary": "Creates list of users with given input array",
"description": "",
"operationId": "createUsersWithArrayInput",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "List of user object",
"required": true,
"schema": { "type": "array", "items": { "$ref": "#/definitions/User" } } }
],
"responses": {
"default": { "description": "successful operation" } }
}
},
"/user/createWithList": {
"post": {
"tags": [
"user"
],
"summary": "Creates list of users with given input array",
"description": "",
"operationId": "createUsersWithListInput",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "List of user object",
"required": true,
"schema": { "type": "array", "items": { "$ref": "#/definitions/User" } } }
],
"responses": {
"default": { "description": "successful operation" } }
}
},
"/user/login": {
"get": {
"tags": [
"user"
],
"summary": "Logs user into the system",
"description": "",
"operationId": "loginUser",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "username",
"in": "query",
"description": "The user name for login",
"required": true,
"type": "string" },
{
"name": "password",
"in": "query",
"description": "The password for login in clear text",
"required": true,
"type": "string" }
],
"responses": {
"200": { "description": "successful operation", "schema": { "type": "string" }, "headers": { "X-Rate-Limit": { "type": "integer", "format": "int32", "description": "calls per hour allowed by the user" }, "X-Expires-After": { "type": "string", "format": "date-time", "description": "date in UTC when token expires" } } },
"400": { "description": "Invalid username/password supplied" } }
}
},
"/user/logout": {
"get": {
"tags": [
"user"
],
"summary": "Logs out current logged in user session",
"description": "",
"operationId": "logoutUser",
"produces": [
"application/xml",
"application/json"
],
"parameters": [],
"responses": {
"default": { "description": "successful operation" } }
}
},
"/user/{username}": {
"get": {
"tags": [
"user"
],
"summary": "Get user by user name",
"description": "",
"operationId": "getUserByName",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "username",
"in": "path",
"description": "The name that needs to be fetched. Use user1 for testing. ",
"required": true,
"type": "string" }
],
"responses": {
"200": { "description": "successful operation", "schema": { "$ref": "#/definitions/User" } },
"400": { "description": "Invalid username supplied" },
"404": { "description": "User not found" } }
},
"put": {
"tags": [
"user"
],
"summary": "Updated user",
"description": "This can only be done by the logged in user.",
"operationId": "updateUser",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "username",
"in": "path",
"description": "name that need to be updated",
"required": true,
"type": "string" },
{
"in": "body",
"name": "body",
"description": "Updated user object",
"required": true,
"schema": { "$ref": "#/definitions/User" } }
],
"responses": {
"400": { "description": "Invalid user supplied" },
"404": { "description": "User not found" } }
},
"delete": {
"tags": [
"user"
],
"summary": "Delete user",
"description": "This can only be done by the logged in user.",
"operationId": "deleteUser",
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "username",
"in": "path",
"description": "The name that needs to be deleted",
"required": true,
"type": "string" }
],
"responses": {
"400": { "description": "Invalid username supplied" },
"404": { "description": "User not found" } }
}
}
},
"securityDefinitions": {
"petstore_auth": {
"type": "oauth2",
"authorizationUrl": "https://petstore.swagger.io/oauth/dialog",
"flow": "implicit",
"scopes": {
"write:pets": "modify pets in your account",
"read:pets": "read your pets"
}
},
"api_key": {
"type": "apiKey",
"name": "api_key",
"in": "header"
}
},
"definitions": {
"Order": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64" },
"petId": {
"type": "integer",
"format": "int64" },
"quantity": {
"type": "integer",
"format": "int32" },
"shipDate": {
"type": "string",
"format": "date-time" },
"status": {
"type": "string",
"description": "Order Status",
"enum": [ "placed", "approved", "delivered" ] },
"complete": {
"type": "boolean",
"default": false }
},
"xml": {
"name": "Order"
}
},
"User": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64" },
"username": {
"type": "string" },
"firstName": {
"type": "string" },
"lastName": {
"type": "string" },
"email": {
"type": "string" },
"password": {
"type": "string" },
"phone": {
"type": "string" },
"userStatus": {
"type": "integer",
"format": "int32",
"description": "User Status" }
},
"xml": {
"name": "User"
}
},
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64" },
"name": {
"type": "string" }
},
"xml": {
"name": "Category"
}
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64" },
"name": {
"type": "string" }
},
"xml": {
"name": "Tag"
}
},
"Pet": {
"type": "object",
"required": [
"name",
"photoUrls"
],
"properties": {
"id": {
"type": "integer",
"format": "int64" },
"category": {
"$ref": "#/definitions/Category" },
"name": {
"type": "string",
"example": "doggie" },
"photoUrls": {
"type": "array",
"xml": { "name": "photoUrl", "wrapped": true },
"items": { "type": "string" } },
"tags": {
"type": "array",
"xml": { "name": "tag", "wrapped": true },
"items": { "$ref": "#/definitions/Tag" } },
"status": {
"type": "string",
"description": "pet status in the store",
"enum": [ "available", "pending", "sold" ] }
},
"xml": {
"name": "Pet"
}
},
"ApiResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32" },
"type": {
"type": "string" },
"message": {
"type": "string" }
}
}
},
"externalDocs": {
"description": "Find out more about Swagger",
"url": "http://swagger.io"
}
}