springboot集成swagger2，构建优雅的Restful API

落日映苍穹つ 2022-05-18 09:55 274阅读 0赞

一、POM配置

<?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    	<modelVersion>4.0.0</modelVersion>
    
    	<groupId>com.example</groupId>
    	<artifactId>springboot-swagger</artifactId>
    	<version>0.0.1-SNAPSHOT</version>
    	<packaging>jar</packaging>
    
    	<name>springboot-swagger</name>
    	<description>Demo project for Spring Boot</description>
    
    	<parent>
    		<groupId>org.springframework.boot</groupId>
    		<artifactId>spring-boot-starter-parent</artifactId>
    		<version>1.5.4.RELEASE</version>
    		<relativePath/> 
    	</parent>
    
    	<properties>
    		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    		<java.version>1.8</java.version>
    	</properties>
    
    	<dependencies>
    		<dependency>
    			<groupId>org.springframework.boot</groupId>
    			<artifactId>spring-boot-starter-web</artifactId>
    		</dependency>
    
    		<dependency>
    			<groupId>org.springframework.boot</groupId>
    			<artifactId>spring-boot-starter-test</artifactId>
    			<scope>test</scope>
    		</dependency>
    
    		<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>
    
    	</dependencies>
    
    	<build>
    		<plugins>
    			<plugin>
    				<groupId>org.springframework.boot</groupId>
    				<artifactId>spring-boot-maven-plugin</artifactId>
    			</plugin>
    		</plugins>
    	</build>
    
    
    </project>

二、写配置类

package com.example.springbootswagger;
    
    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.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class Swagger2 {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger"))
                    .paths(PathSelectors.any())
                    .build();
        }
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("springboot利用swagger构建api文档")
                    .description("简单优雅的restfun风格，https://blog.csdn.net/whj826069748/article/details/81355129")
                    .termsOfServiceUrl("https://blog.csdn.net/whj826069748/article/details/81355129")
                    .version("1.0")
                    .build();
        }
    }

三、Controller接口

package com.example.springbootswagger;
    
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.*;
    import springfox.documentation.annotations.ApiIgnore;
    
    import java.util.*;
    
    @RestController
    @RequestMapping(value = "/books")
    public class BookContrller {
    
        Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());
    
        @ApiOperation(value = "获取图书列表", notes = "获取图书列表")
        @RequestMapping(value = {""}, method = RequestMethod.GET)
        public List<Book> getBook() {
            List<Book> book = new ArrayList<>(books.values());
            return book;
        }
    
        @ApiOperation(value = "创建图书", notes = "创建图书")
        @ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book")
        @RequestMapping(value = "", method = RequestMethod.POST)
        public String postBook(@RequestBody Book book) {
            books.put(book.getId(), book);
            return "success";
        }
    
        @ApiOperation(value = "获图书细信息", notes = "根据url的id来获取详细信息")
        @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 = "更新信息", notes = "根据url的id来指定更新图书信息")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long", paramType = "path"),
                @ApiImplicitParam(name = "book", value = "图书实体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 = "删除图书", notes = "根据url的id来指定删除图书")
        @ApiImplicitParam(name = "id", value = "图书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//使用该注解忽略这个API
        @RequestMapping(value = "/hi", method = RequestMethod.GET)
        public String jsonTest() {
            return " hi you!";
        }
    }

四、实体类

package com.example.springbootswagger;
    
    public class Book {
    
        private Long id;
        private String name;
        private String price;
    
        public Long getId() {
            return id;
        }
    
        public void setId(Long id) {
            this.id = id;
        }
    
        public String getName() {
            return name;
        }
    
        public void setName(String name) {
            this.name = name;
        }
    
        public String getPrice() {
            return price;
        }
    
        public void setPrice(String price) {
            this.price = price;
        }
    }

**注意：如果请求参数在url上，@ApiImplicitParam 上加paramType = “path”**

启动工程，访问：[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html] ，就看到swagger-ui:

![70][]

github地址：[https://github.com/whj826069748/springboot-swagger][https_github.com_whj826069748_springboot-swagger]

[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[70]: /images/20220518/80c7f083c6544e73aeee027787ba9a6c.png
[https_github.com_whj826069748_springboot-swagger]: https://github.com/whj826069748/springboot-swagger