Swagger-API documentation interface engine
Swagger is what
Swagger is a standardized and complete framework for generating, description, and visualization calls for RESTful Web services. The overall objective is to make the client and the file system as a server at the same rate updates. Methods, parameters and models are tightly integrated into the file server-side code that allows the API to always be in sync.
In project development, business code is automatically generated based on the API documentation provided to the front-line test, automatic display JSON format to facilitate communication and commissioning costs of the back-end and front-end.
Swagger has a drawback is intrusive mode, you must be arranged in a particular code.
Use Swagger (SpringBoot + Swagger integration)
New Maven project
a first embodiment: use of third party reliance
1. Adding a third party in dependence swagger pom.xml file
<dependency>
<the groupId> com.spring4all </ the groupId>
<the artifactId> swagger Starter-boot--spring </ the artifactId>
<Version> 1.7.0.RELEASE </ Version>
</ dependency>
2, was added in the starting class @ EnableSwagger2 Spring boot project start Swagger
. 3, HTTPS: // GitHub.
第二种方式：使用官方依赖
1.在pom.xml文件中添加swagger相关依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>org.codehaus.jackson</groupId>
<artifactId>jackson-core-asl</artifactId>
<version>1.9.13</version>and the second is a given official ui interface, this interface can be customized, the default is the official The first API is the acquired packet
</ dependency>
The third test data is returned in JSON format dependencies
Configuration Swagger
new class Swagger configuration, special attention is required Swagger scan base package, which is a scan of sample configuration, i.e., the position of your API interfaces, provide services for the distal end the position of the interface.
com.example.demo.config Package Penalty for;
@Configuration
@ EnableSwagger2
public class SwaggerConfig {
Private ApiInfo apiInfo () {
return new new ApiInfoBuilder () title ( "API interface documentation").
.description ( "User Information Management")
.version ( " 1.0.0 ")
.build ();
}
@Bean
public Docket No. createRestApi () {
return new new Docket No. (DocumentationType.SWAGGER_2)
.apiInfo (apiInfo ())
.Select ()
.apis (RequestHandlerSelectors.basePackage ( "com.example.demo.controller") ) // packet is written here the position where the API interface
.paths (PathSelectors.any ())
.build ();
}
}
3. Write simple Dao and a User entity class
Package com.example.demo.dao;
Import com.example.demo.entity.User;
public interface UserDao {
User the findById (ID Integer);
User the findByName (String name);
}
public class User {
int id; // user ID
String name; // name
public void the setId (int ID) {
this.id ID =;
}
public int getId () {
return ID;
}
Public void the setName (String name) {
this.name = name;
}
public String getName () {
return name;
}
4. Write the Controller (the UserController)
@RestController
@RequestMapping ( "/ User")
@Api (value = "User information management ")
public class the UserController {
UserDao userDao;
@RequestMapping (Method = RequestMethod.POST, value =" / userById ")
@ApiOperation (value =" get user information ", notes =" get user information through the user ID ")
public Object findById (@ApiParam (value = "user ID", required = to true) int ID) {
return userDao.findById (ID);
}
@RequestMapping (Method = RequestMethod.POST, value = "/ userByName")
@ApiOperation (value = "get user information", notes = "get user information through the user's name")
public Object the findByName (@ApiParam (value = "User Name ", required to true =) String name) {
return userDao.findByName (name);
}
}
5. the set route to access the API documentation
in the configuration file, application.yml declared:
springfox.documentation.swagger.v2.path: / api-docs
this path is json access request mapping. You can customize to prevent conflict with its own code.
API doc is displayed route: HTTP: // localhost: 8080 / The ui.html-Swagger
Swagger common annotation
. 1, labeled Api
Api with class, the role of the class described. Controller class can mark a document as a swagger resources, use:
@Api (value = "/ the User", the Description = "the Operations the About the User")
2, ApiOperation mark
ApiOperation: used in the method, the method described effect, define each url resource use:
@ApiOperation (
value = "ID by the Find Purchase Order",
Notes = "Integer the For Valid Response IDs with the try value <=. 5 or > 10. The values Will Generated Other Exceptions ",
Response = the Order,
Tags = {" the Pet Store "})
. 3, ApiParam tag
ApiParam request attributes, use:
public ResponseEntity <the User> the createUser (@RequestBody @ApiParam (value =" the Created Object User ", required = to true) the User User)
4. ApiResponse
ApiResponse: in response to configuration, use:
@ApiResponse (code = 400, Message =" Invalid User Supplied ")
5. The ApiResponses
ApiResponses: response set configuration, use:
@ ApiResponses ({@ApiResponse (code = 400 , message = "Invalid Order") })
6. ResponseHeader
response header, use
@ResponseHeader (name = "head1", Description = "Response head the conf")
@Api () for the class;
a flag indicating the class of the resource swagger
@ApiOperation () method is used;
It represents a http request operation
@ApiParam () method is used, parameter field specifies;
represents adding metadata parameters (if required instructions or the like)
@ApiModel () for class
represents the class explained, the parameters receiving entity class
@ApiModelProperty () method is used, the field
indicates the description of the data model attributes or operations change
@ApiIgnore () for classes, methods, method parameters
indicates that this method or class are ignored
@ApiImplicitParam () method for
showing separate request parameter
@ApiImplicitParams () method is used, comprising a plurality of @ApiImplicitParam
@Api ()
for the class; swagger represent this class is identified resource
tags- explanatory
value- are described, alternate tags may be used
, but if tags a plurality of values, generates a plurality List
@Api (value = "user controller", tags = { "user Interface operation"})
@RestController
public class the UserController {
}
@ApiOperation () method is used; http request operation represents a
value used to describe a method
notes for prompting content
tags can regroup (Conditional use)
@ApiParam () method is used, the parameters , field Description; represents adding metadata parameters (required instructions or the like)
name- parameter name
value- parameter Description
required- required
@ApiModel () for the class; represents a class is described, for parameters receiving entity class
value- object name indicates
description- description
can be omitted
@ApiModelProperty () method is used, the field; an explanatory model or attributes of the data change operation
value- field Description
name- override attribute name
dataType- override attribute type
required- required
example- illustrated
hidden- hidden
@ApiIgnore () on a class or method can not be displayed on the page swagger
relatively simple, do not make for example
@ApiImplicitParam () method is used
which represents a separate request parameters
@ApiImplicitParams () method is used, comprising a plurality @ApiImplicitParam
name- parameters Ming
value- Parameter Description
dataType- Data Type
paramType- Parameter Type
example- illustrated
----------------- ----------------> Basics ---------------------
Disclaimer: This article is CSDN bloggers' ai_miracle "the original article, follow the CC 4.0 by-sa copyright agreement, reproduced, please attach the original source link and this statement.
Original link: https: //blog.csdn.net/ai_miracle/article/details/82709949
[Turn] Detailed Swagger (SpringBoot + Swagger integration)
Guess you like
Origin www.cnblogs.com/wangwangfei/p/11346545.html
Recommended
Ranking