springboot学习(二):使用Swagger2构建RESTful API

朴灿烈づ我的快乐病毒、 2022-05-17 01:20 236阅读 0赞

# 说明 #

在第一次学习本节内容时，没有很重视只是走了遍流程，当学到springcloud微服务，众多微服务的API文档都分散在各自的服务中，如何聚集到一起，就需要通过Swagger2在网关中聚集，在此回顾下当初springboot中Swagger2的用法。

# 正文 #

构建springboot项目，引入依赖包，这里我使用放在本地的tomcat启动，所以也引入了web依赖

<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>javax.servlet</groupId>
                <artifactId>javax.servlet-api</artifactId>
                <version>3.1.0</version>
                <scope>compile</scope>
            </dependency>
    
            
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.8.0</version>
            </dependency>
            
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.8.0</version>
            </dependency>
     </dependencies>

引入依赖后需要创建一个配置类，该类可以放在与Application类同级，可以放在自创的config包中，这里放在config包中

@Configuration
    @EnableSwagger2
    public class Swagger2 { 
    
        @Bean
        public Docket creatRestApi(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo()).select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")) //扫描该包下所有的controller
                    .paths(PathSelectors.any()).build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Swagger RESTful APIs ")  //API文档标题
                    .description("学习swagger构建restful api") // 文档描述
                    .termsOfServiceUrl("")
                    .version("1.0")
                    .build();
        }
    }

配置好之后，创建controller为具体方法添加描述

@RestController("/test")
    public class TestController { 
    
        @ApiOperation(value = "hello",notes = "输出hello world")
        @RequestMapping("/hello")
        public String hello(){
            return "hello world";
        }
    
        @ApiOperation(value = "list",notes = "查询相关内容")
        @GetMapping("list")
        public String add(){
            return "list";
        }
    
        @ApiOperation(value = "update",notes = "更新相关内容")
        @ApiImplicitParam(name = "params",value = "更新的内容",required = true,dataType = "String")
        @PostMapping("update")
        public String update(String params){
            return "update";
        }
    
        @ApiOperation(value = "delete", notes = "删除相关内容")
        @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
        @PostMapping("delete{id}")
        public String delete(@PathVariable String id){
            return "delete";
        }
    
    }

启动tomcat，访问[http://localhost:8081/swagger/swagger-ui.html\#/][http_localhost_8081_swagger_swagger-ui.html]，可以看到  
![这里写图片描述][20180804125256277]

通过API文档可以看到，当hello方法没有指定具体的HTTP请求方法类型时，文档会自动创建所有类型的api

点击try it out 进行测试  
![这里写图片描述][20180804130137668]

源码地址：[https://github.com/Edenwds/springboot\_study/tree/master/swagger][https_github.com_Edenwds_springboot_study_tree_master_swagger]

参考：[http://blog.didispace.com/springbootswagger2/][http_blog.didispace.com_springbootswagger2]

[http_localhost_8081_swagger_swagger-ui.html]: http://localhost:8081/swagger/swagger-ui.html#/
[20180804125256277]: /images/20220517/901a666d66294bc8b5318ef6e76f26ab.png
[20180804130137668]: /images/20220517/a6a70210752748b28bc54aa806ffedee.png
[https_github.com_Edenwds_springboot_study_tree_master_swagger]: https://github.com/Edenwds/springboot_study/tree/master/swagger
[http_blog.didispace.com_springbootswagger2]: http://blog.didispace.com/springbootswagger2/