Preface
swagger, the Chinese meaning of "swallow". It is a powerful API framework, its integration is very simple, not only provides online documentation review,
Also, online documentation is provided. In addition, swagger is easy to build restful-style APIs.
Swagger is a set of open source tools built around the OpenAPI specification to help design, build, document and use REST APIs.
Simply put, it appears to facilitate testing the restful interface in the background and implement dynamic updates when we are in the background interface.
After modification, swagger can automatically update without the need to maintain this interface for testing as you think.
Swagger indicates through annotation that the interface will generate a document, including interface name, request method, parameters, return information, etc.
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version></dependency><dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version></dependency>
Through the @Configuration annotation, it indicates that it is a configuration class, and @EnableSwagger2 enables swagger2.
apiINfo() configuration some basic information. apis() specifies that the scanned package will generate a document.
After creating the Docket bean through the createRestApi function, apiInfo() uses the basic information of the API (these basic information will be displayed in the document page). The select() function returns an ApiSelectorBuilder instance to control which interfaces are exposed to Swagger for display. This example uses the specified scanned package path to define. Swagger will scan all the APIs defined by the Controller under the package and generate document content (except the request specified by @ApiIgnore).
package com.lance.learn.springbootswagger.configuration;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * @author lance(ZYH) * @function Swagger startup configuration class* @date 2018-07-09 21:24 */@Configuration@EnableSwagger2public class SwaggerConfiguration { /** * swagger2 configuration file, you can configure some basic contents of swagger2, such as scanned packages, etc. * @return */ @Bean public Docket createRestfulApi(){ return new Docket(DocumentationType.SWAGGER_2) .pathMapping("/") .select() .apis(RequestHandlerSelectors.basePackage("com.lance.learn.springbootswagger.controller")) //Expose the package path of the interface address.paths(PathSelectors.any()) .build(); } /** * Build the detailed information function of the API document, note which annotation refers to * @return */ private ApiInfo apiInfo(){ return new ApiInfoBuilder() //Page title.title("Spring Boot test to build RESTful API using Swagger2") //Create.contact(new Contact("LanveToBigData", "http://www.cnblogs.com/zhangyinhua/", "[email protected]")) //version number.version("1.0") //Description("API Description") .build(); }} Descriptions mainly come from naming functions, etc., and are not user-friendly. We usually need to add some instructions to enrich the content of the document.
As shown below, we add instructions to the API through @ApiOperation annotation, and use @ApiImplicitParams and @ApiImplicitParam
Annotation to add description to the parameters.
1) Example 1
package com.lance.learn.springbootswagger.controller;import com.lance.learn.springbootswagger.bean.Book;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;import org.springframework.web.bind.annotation.*;import springfox.documentation.annotations.ApiIgnore;import java.util.*;/** * @author lance(ZYH) * @function * @date 2018-07-09 21:39 */@RestController@RequestMapping(value = "/bookcurd")public class BookController { Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>()); @ApiOperation(value="get book list", notes="get book list") @RequestMapping(value={""}, method= RequestMethod.GET) public List<Book> getBook() { List<Book> book = new ArrayList<>(books.values()); return book; } @ApiOperation(value="Create a book", notes="Create a book") @ApiImplicitParam(name = "book", value = "Book detailed entity", required = true, dataType = "Book") @RequestMapping(value="", method=RequestMethod.POST) public String postBook(@RequestBody Book book) { books.put(book.getId(), book); return "success"; } @ApiOperation(value="get detailed information on the book", notes="get detailed information based on the id of the url") @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long",paramType = "path") @RequestMapping(value="/{id}", method=RequestMethod.GET) public Book getBook(@PathVariable Long id) { return books.get(id); } @ApiOperation(value="Update information", notes="Specify update book information based on the url's id") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "Book ID", required = true, dataType = "Long",paramType = "path"), @ApiImplicitParam(name = "book", value = "book entity book", required = true, dataType = "Book") }) @RequestMapping(value="/{id}", method= RequestMethod.PUT) public String putUser(@PathVariable Long id, @RequestBody Book book) { Book book1 = books.get(id); book1.setName(book.getName()); book1.setPrice(book.getPrice()); books.put(id, book1); return "success"; } @ApiOperation(value="delete book", notes="Specify deletion of books based on the id of the url") @ApiImplicitParam(name = "id", value = "book ID", required = true, dataType = "Long",paramType = "path") @RequestMapping(value="/{id}", method=RequestMethod.DELETE) public String deleteUser(@PathVariable Long id) { books.remove(id); return "success"; } @ApiIgnore//Use this annotation to ignore this API @RequestMapping(value = "/hi", method = RequestMethod.GET) public String jsonTest() { return " hi you!"; }}2) Example 2
package com.lance.learn.springbootswagger.controller;import com.lance.learn.springbootswagger.bean.User;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;import org.springframework.web.bind.annotation.*;import java.util.*;/** * @author lance(ZYH) * @function * @date 2018-07-09 22:00 */@RestController@RequestMapping(value="/users")public class UserDetailController { static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>()); @ApiOperation(value="get user list", notes="") @RequestMapping(value={""}, method= RequestMethod.GET) public List<User> getUserList() { List<User> r = new ArrayList<User>(users.values()); return r; } @ApiOperation(value="Create user", notes="Create user from User object") @ApiImplicitParam(name = "user", value = "User detailed entity user", required = true, dataType = "User") @RequestMapping(value="", method=RequestMethod.POST) public String postUser(@RequestBody User user) { users.put(user.getId(), user); return "success"; } @ApiOperation(value="get user details", notes="get user details based on the id of the url") @ApiImplicitParam(name = "id", value = "User ID", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.GET) public User getUser(@PathVariable Long id) { return users.get(id); } @ApiOperation(value="Update user details", notes="Specify update objects based on the id of the url, and update user details based on the transmitted user information") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "User ID", required = true, dataType = "Long"), @ApiImplicitParam(name = "user", value = "User detailed entity user", required = true, dataType = "User") }) @RequestMapping(value="/{id}", method=RequestMethod.PUT) public String putUser(@PathVariable Long id, @RequestBody User user) { User u = new User(); users.put(id, u); return "success"; } @ApiOperation(value="Delete user", notes="Specify delete object according to the id of the url") @ApiImplicitParam(name = "id", value = "User ID", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.DELETE) public String deleteUser(@PathVariable Long id) { users.remove(id); return "success"; }}https://github.com/LanceToBigData/SpringBootLearning/tree/develop/SpringBoot-Swagger
Summarize
The above is the entire content of this article. I hope that the content of this article has certain reference value for everyone's study or work. If you have any questions, you can leave a message to communicate. Thank you for your support to Wulin.com.