1. Introduction
Swagger's goal is to define a language-independent standard interface for the REST API, allowing users to discover and understand the functionality of computer services without accessing source code. When correctly defined by Swagger, users can understand and interact with remote services with a minimum amount of implementation logic. Similar to the interface made by low-level programming.
2. Implementation steps
1. Add Maven dependencies
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version></dependency>
2. Swagger configuration class
@Configuration@EnableSwagger2//@ComponentScan(basePackageClasses = JgBjBaseInfoCompanyApi.class) or @ComponentScan(basePackages = "com.summersoft.ts.schedule.supervision.controller") //The package path to scan public class SwaggerConfig { @Bean public Docket swaggerSpringMvcPlugin() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //Selecting which paths and api will generate document .apis(RequestHandlerSelectors.any())//Supervising all APIs.paths(PathSelectors.any()) //Scan all paths.build(); } /** * api specific information* * @return */ private ApiInfo apiInfo apiInfo() { ApiInfo apiInfo = new ApiInfo( "Dooring Service Platform API Document", //Title"", //Description "1.0", //Release", "", "", "", //Signature"" //Signature link); return apiInfo; }}3. Swagger Notes
Swagger will scan the class file with Swagger annotation under the package path configured in SwaggerConfig, and finally generate a series of scanned Json files...
Swagger annotation description: https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel
@Api: Used on a class to illustrate the function of the class. It should be noted that the value used in older versions represents the class name generated by scanning. After 1.5, tag should be used to represent the class name.
@Api(tag= "UserController", description = "User-related api")
@ApiOperation: Used in methods to illustrate the function of methods
@ApiOperation(value = "Find User", notes = "Find User", httpMethod = "GET", produces =
MediaType.APPLICATION_JSON_UTF8_VALUE)
@ApiParam: Used in the parameter list to indicate the meaning of the parameter
@ApiParam(value = "Create or update the current time (month)") Integer time
@ApiImplicitParams: Used to include a set of parameter descriptions on the method
@ApiImplicitParam: Used in @ApiImplicitParams annotation, specifying various aspects of a request parameter
paramType: Where to place the parameter
header>Request parameter acquisition: @RequestHeader
query>Request parameter acquisition: @RequestParam
path (for restful interface)>Getting of request parameters: @PathVariable
body (not commonly used)
form (not commonly used)
name: parameter name
dataType: parameter type
required: Whether the parameter must be passed
value: the meaning of the parameter
defaultValue: The default value of the parameter
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "unique id", required = true, dataType = "Long", paramType = "path"),
})
@ApiResponses: used to represent a set of responses
@ApiResponse: Used in @ApiResponses, it is generally used to express an error response information
code: number, for example 400
message: information, such as "request parameters not filled out"
response: class that throws exception
@ApiResponses(value = {
@ApiResponse(code = 400, message = "No Name Provided")
})
@ApiModel: Describes the information of a Model (this is usually used when creating a post, using @RequestBody scenarios, and the request parameters cannot be described using @ApiImplicitParam annotation)
@ApiModel(value = "User Entity Class")
@ApiModelProperty: Describe the properties of a model
@ApiModelProperty(value = "Login user")
3. Swagger-ui
With the above configuration information, Swagger will help us scan out all class information and generate a JSON file. To make JSON files friendly to people, you need to use the swagger-ui component:
1. Swagger-ui Instructions: https://swagger.io/docs/swagger-tools/
2. Download swagger-ui, create a new swagger directory in the webapp directory, put the files in the dist directory into the swagger directory, and modify the index.html file. By default, you need to get the JSON of the API from the connection http://petstore.swagger.io/v2/swagger.json. Here you need to modify the url value to http://{ip}:{port}/{projectName}/api-docs, and the values in {} are filled in according to their own situation.
For example, my url value is:
http://localhost:8080/vouchers/api-docs . In addition, you need to configure the resource release of Spring MVC: <mvc:resources mapping="/swagger/**" location="/swagger/"/>
tips: There are not so many files in the default dist directory. Swagger-ui can be customized. This is used in our project. There is no need to change the project name. The project name is dynamically obtained: https://files.cnblogs.com/files/jmcui/swagger.zip
3. How to sort the displayed interfaces:
apisSorter: Apply sorting to the API/tag list. It can be 'alpha' (sorted by name) or a function (see Array.prototype.sort() for how sort functions work). The default is that the order returned by the server remains unchanged.
operationsSorter: Apply a sort to the operation list for each API. It can be 'alpha' (sorted by alphanumeric), 'method' (sorted by HTTP method) or function (see Array.prototype.sort() to know how sort functions work). The default is that the order returned by the server remains unchanged.
The above tutorial (share) for configuring the Swagger plug-in in SpringMVC is all the content I share with you. I hope you can give you a reference and I hope you can support Wulin.com more.