spring boot基础知识 —— spring boot 集成 swagger2

今天药忘吃喽~ 2022-12-06 15:20 162阅读 0赞

码云地址：[https://gitee.com/hjc2/springboot.git][https_gitee.com_hjc2_springboot.git]

需要添加的依赖如下：

<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>
          
          
             
                
                
             
          
       </dependency>
    
       <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger2</artifactId>
          <version>2.9.2</version>
       </dependency>
    
       <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger-ui</artifactId>
          <version>2.9.2</version>
       </dependency>
    </dependencies>

先介绍几个注解：

@EnableSwagger2    开启swagger2

@Api(value = "测试相关的接口")  表示controller的作用

@ApiOperation(value = "首次访问接口")  作用在方法上，表示方法的作用

@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id", defaultValue = "1", required = true)})

传入的参数

如果传入的参数是实体，那么实体上应该有以下几个注解：

@ApiModel  实体表示

@ApiModelProperty(value = "书籍的id编号")  具体参数

下面开始说明如何集成：

首先需要一个swagger的配置，返回一个Doctet，具体代码如下：

@Configuration
    // 开启 swagger2
    @EnableSwagger2
    public class SwaggerConfig {
        // 提供一个 Docket的bean
        @Bean
        public Docket createRestApi() {
            Docket docket = new Docket(DocumentationType.SWAGGER_2);
            docket.pathMapping("/").select().
                    apis(RequestHandlerSelectors.basePackage("com.dream.controller")).
                    paths(PathSelectors.any()).build().
                    apiInfo(new ApiInfoBuilder().title("SpringBoot整合Swagger").
                            description("SpringBoot整合Swagger，详细信息......").
                            version("1.0").contact(new Contact("name", "blog.csdn.net", "aaa@gmail.com")).
                            license("The Apache License").licenseUrl("http://www.baidu.com").build());
            return docket;
        }
    }

配置文件：

server.port=8081

然后运行工程，输入地址：[http://localhost:8081/swagger-ui.html][http_localhost_8081_swagger-ui.html]，出现下面这个界面表示整合成功

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hfal9jXzEyMw_size_16_color_FFFFFF_t_70][]

然后需要的就是写一些controller，具体代码如下：

@RestController
    @RequestMapping(value = "/book")
    // api是用来标记controller的功能
    @Api(value = "测试相关的接口")
    public class IndexController {
        // ApiOperation标记一个方法
        @ApiOperation(value = "首次访问接口")
        @RequestMapping(value = "/index",method = RequestMethod.GET)
        // 传入的参数
        @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id", defaultValue = "1", required = true)})
        public String index(int id) {
            return "hello index\t" + id;
        }
    
        @ApiOperation(value = "书籍接口")
        @RequestMapping(value = "/book")
        @ApiImplicitParams({@ApiImplicitParam(name = "BookEntity")})
        public String hi(BookEntity bookEntity) {
            System.out.println(bookEntity);
            return bookEntity.toString();
        }
    }

实体代码如下：

// 书籍实体
    @ApiModel
    public class BookEntity {
        @ApiModelProperty(value = "书籍的id编号")
        private String bookId;
        @ApiModelProperty(value = "书籍的名称")
        private String bookName;
    
        public String getBookId() {
            return bookId;
        }
    
        public void setBookId(String bookId) {
            this.bookId = bookId;
        }
    
        public String getBookName() {
            return bookName;
        }
    
        public void setBookName(String bookName) {
            this.bookName = bookName;
        }
    }

打开地址会看到具体的参数：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hfal9jXzEyMw_size_16_color_FFFFFF_t_70 1][]

\{  
    "swagger":"2.0",  
    "info":\{  
        "description":"SpringBoot整合Swagger，详细信息......",  
        "version":"1.0",  
        "title":"SpringBoot整合Swagger",  
        "contact":\{  
            "name":"name",  
            "url":"blog.csdn.net",  
            "email":"aaa@gmail.com"  
        \},  
        "license":\{  
            "name":"The Apache License",  
            "url":"[http://www.baidu.com][http_www.baidu.com]"  
        \}  
    \},  
    "host":"localhost:8081",  
    "basePath":"/",  
    "tags":\[  
        \{  
            "name":"index-controller",  
            "description":"Index Controller"  
        \}  
    \],  
    "paths":\{  
        "/book/book":\{  
            "get":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"书籍接口",  
                "operationId":"hiUsingGET",  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"BookEntity",  
                        "required":false,  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    \{  
                        "name":"bookId",  
                        "in":"query",  
                        "description":"书籍的id编号",  
                        "required":false,  
                        "type":"string"  
                    \},  
                    \{  
                        "name":"bookName",  
                        "in":"query",  
                        "description":"书籍的名称",  
                        "required":false,  
                        "type":"string"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \},  
                    "404":\{  
                        "description":"Not Found"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "head":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"书籍接口",  
                "operationId":"hiUsingHEAD",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"BookEntity",  
                        "required":false,  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    \{  
                        "name":"bookId",  
                        "in":"query",  
                        "description":"书籍的id编号",  
                        "required":false,  
                        "type":"string"  
                    \},  
                    \{  
                        "name":"bookName",  
                        "in":"query",  
                        "description":"书籍的名称",  
                        "required":false,  
                        "type":"string"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "204":\{  
                        "description":"No Content"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "post":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"书籍接口",  
                "operationId":"hiUsingPOST",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"BookEntity",  
                        "required":false,  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    \{  
                        "name":"bookId",  
                        "in":"query",  
                        "description":"书籍的id编号",  
                        "required":false,  
                        "type":"string"  
                    \},  
                    \{  
                        "name":"bookName",  
                        "in":"query",  
                        "description":"书籍的名称",  
                        "required":false,  
                        "type":"string"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "201":\{  
                        "description":"Created"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \},  
                    "404":\{  
                        "description":"Not Found"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "put":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"书籍接口",  
                "operationId":"hiUsingPUT",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"BookEntity",  
                        "required":false,  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    \{  
                        "name":"bookId",  
                        "in":"query",  
                        "description":"书籍的id编号",  
                        "required":false,  
                        "type":"string"  
                    \},  
                    \{  
                        "name":"bookName",  
                        "in":"query",  
                        "description":"书籍的名称",  
                        "required":false,  
                        "type":"string"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "201":\{  
                        "description":"Created"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \},  
                    "404":\{  
                        "description":"Not Found"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "delete":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"书籍接口",  
                "operationId":"hiUsingDELETE",  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"BookEntity",  
                        "required":false,  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    \{  
                        "name":"bookId",  
                        "in":"query",  
                        "description":"书籍的id编号",  
                        "required":false,  
                        "type":"string"  
                    \},  
                    \{  
                        "name":"bookName",  
                        "in":"query",  
                        "description":"书籍的名称",  
                        "required":false,  
                        "type":"string"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "204":\{  
                        "description":"No Content"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "options":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"书籍接口",  
                "operationId":"hiUsingOPTIONS",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"BookEntity",  
                        "required":false,  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    \{  
                        "name":"bookId",  
                        "in":"query",  
                        "description":"书籍的id编号",  
                        "required":false,  
                        "type":"string"  
                    \},  
                    \{  
                        "name":"bookName",  
                        "in":"query",  
                        "description":"书籍的名称",  
                        "required":false,  
                        "type":"string"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "204":\{  
                        "description":"No Content"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "patch":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"书籍接口",  
                "operationId":"hiUsingPATCH",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"BookEntity",  
                        "required":false,  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    \{  
                        "name":"bookId",  
                        "in":"query",  
                        "description":"书籍的id编号",  
                        "required":false,  
                        "type":"string"  
                    \},  
                    \{  
                        "name":"bookName",  
                        "in":"query",  
                        "description":"书籍的名称",  
                        "required":false,  
                        "type":"string"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "204":\{  
                        "description":"No Content"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \}  
                \},  
                "deprecated":false  
            \}  
        \},  
        "/book/index":\{  
            "get":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"首次访问接口",  
                "operationId":"indexUsingGET",  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"id",  
                        "in":"query",  
                        "description":"id",  
                        "required":true,  
                        "type":"string",  
                        "default":"1"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \},  
                    "404":\{  
                        "description":"Not Found"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "head":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"首次访问接口",  
                "operationId":"indexUsingHEAD",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"id",  
                        "in":"query",  
                        "description":"id",  
                        "required":true,  
                        "type":"string",  
                        "default":"1"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "204":\{  
                        "description":"No Content"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "post":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"首次访问接口",  
                "operationId":"indexUsingPOST",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"id",  
                        "in":"query",  
                        "description":"id",  
                        "required":true,  
                        "type":"string",  
                        "default":"1"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "201":\{  
                        "description":"Created"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \},  
                    "404":\{  
                        "description":"Not Found"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "put":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"首次访问接口",  
                "operationId":"indexUsingPUT",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"id",  
                        "in":"query",  
                        "description":"id",  
                        "required":true,  
                        "type":"string",  
                        "default":"1"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "201":\{  
                        "description":"Created"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \},  
                    "404":\{  
                        "description":"Not Found"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "delete":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"首次访问接口",  
                "operationId":"indexUsingDELETE",  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"id",  
                        "in":"query",  
                        "description":"id",  
                        "required":true,  
                        "type":"string",  
                        "default":"1"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "204":\{  
                        "description":"No Content"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "options":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"首次访问接口",  
                "operationId":"indexUsingOPTIONS",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"id",  
                        "in":"query",  
                        "description":"id",  
                        "required":true,  
                        "type":"string",  
                        "default":"1"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "204":\{  
                        "description":"No Content"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \}  
                \},  
                "deprecated":false  
            \},  
            "patch":\{  
                "tags":\[  
                    "index-controller"  
                \],  
                "summary":"首次访问接口",  
                "operationId":"indexUsingPATCH",  
                "consumes":\[  
                    "application/json"  
                \],  
                "produces":\[  
                    "\*/\*"  
                \],  
                "parameters":\[  
                    \{  
                        "name":"id",  
                        "in":"query",  
                        "description":"id",  
                        "required":true,  
                        "type":"string",  
                        "default":"1"  
                    \}  
                \],  
                "responses":\{  
                    "200":\{  
                        "description":"OK",  
                        "schema":\{  
                            "type":"string"  
                        \}  
                    \},  
                    "204":\{  
                        "description":"No Content"  
                    \},  
                    "401":\{  
                        "description":"Unauthorized"  
                    \},  
                    "403":\{  
                        "description":"Forbidden"  
                    \}  
                \},  
                "deprecated":false  
            \}  
        \}  
    \}  
\}

还可以在[http://localhost:8081/swagger-ui.html][http_localhost_8081_swagger-ui.html] 页面看到接口信息：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hfal9jXzEyMw_size_16_color_FFFFFF_t_70 2][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hfal9jXzEyMw_size_16_color_FFFFFF_t_70 3][]

欢迎关注我的微信公众号,更多内容将在微信公众号中发布：

![20201214163531501.jpg][]

[https_gitee.com_hjc2_springboot.git]: https://gitee.com/hjc2/springboot.git
[http_localhost_8081_swagger-ui.html]: http://localhost:8081/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hfal9jXzEyMw_size_16_color_FFFFFF_t_70]: /images/20221123/d68efc72f25f4027bb66765cd991430c.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hfal9jXzEyMw_size_16_color_FFFFFF_t_70 1]: /images/20221123/32889b7544334d1a83628e2d4cea33cf.png
[http_www.baidu.com]: http://www.baidu.com/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hfal9jXzEyMw_size_16_color_FFFFFF_t_70 2]: /images/20221123/4d98284f14784e2583669d0463370d12.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hfal9jXzEyMw_size_16_color_FFFFFF_t_70 3]: /images/20221123/d9b58ccfd56d4de29e2109e25b8cd6cb.png
[20201214163531501.jpg]: /images/20221123/0171b92505c24201abccc2d3465da69c.png