美文网首页
Swagger2的配置使用

Swagger2的配置使用

作者: Dcl_Snow | 来源:发表于2019-12-26 16:53 被阅读0次

概述

随着前后端分离架构和微服务架构的流行，使用Spring Boot来构建RESTful API项目的场景越来越多。通常一个RESTful API就有可能要服务于多个不同的开发人员或开发团队：IOS开发、Android开发、Web开发甚至其他的后端服务等。
为了减少与其他团队平时开发期间的频繁沟通成本，常规方式是创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：

  1. 由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就非常吃力。
  2. 随着开发工作的进展，不断修改接口实现的时候，必须同步更新接口文档，而文档与代码又处于两个不同的媒介，很容易出现不一致。
  3. 开发人员完成接口开发后，需要进行测试和调试，此时就需要类似Postman工具软件或者在浏览器上安装类似功能的插件，才能进行测试。

为了解决上面的问题，这里使用Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合生成强大RESTful API文档。它既可以减少创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以在修改代码逻辑的同时方便的修改文档说明。
而且Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

一、Swagger2的使用

配置

  1. POM文件引入依赖：
<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>
  1. 在启动类同级，创建配置类：
@Configuration
@EnableSwagger2
public class Swagger {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() // 选择那些路径和api会生成document
           .apis(RequestHandlerSelectors.basePackage("com.routon.datadisplayplatform.controller")) //对该路径下api进行监控
                .paths(PathSelectors.any()) //对所有路径进行监控
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("大数据展示平台")
                .description("大数据平台数据展示的RESTful APIs")
                .contact("Dcl_Snow")
                .version("1.0")
                .build();
    }

}
  1. 在Controller接口类中进行注释：
@Api(tags = "用户管理接口")
@RestController
@RequestMapping("/users")
public class UserController {
    static Map<Long,User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    @ApiOperation(value="获取用户列表", notes="")
    @RequestMapping(value = "/",method = RequestMethod.GET)
    public List<User> getUserList(){
        List<User> list = new ArrayList<>(users.values());
        return list;
    }

    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = false, dataType = "User")
    @RequestMapping(value = "",method = RequestMethod.POST)
    public String postUser(@ModelAttribute User user){
        users.put(user.getId(),user);
        return "success";
    }

    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value = "/{id}",method = RequestMethod.GET)
    public User getUser(@PathVariable Long id){
        return users.get(id);
    }

    @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = false, dataType = "User")
    })
    @RequestMapping(value = "/{id}",method = RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @ModelAttribute User user){
        User user1 = users.get(id);
        user1.setName(user.getName());
        user1.setAge(user.getAge());
        users.put(id,user1);
        return "success";
    }

    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
    public String deleteUser(@PathVariable Long id){
        users.remove(id);
        return "success";
    }
}
  1. 在实体类中进行注释：
@ApiModel(value = "User", description = "用户实体User")
@Gettter
@Setter
public class User {
    @ApiModelProperty(value = "用户编号", name = "id")
    private Long id;
    @ApiModelProperty(value = "用户姓名", name = "username")
    private String name;
    @ApiModelProperty(value = "用户年龄", name = "年龄")
    private Integer age;
}

参数解释

@Api：用在请求的Controller类上，修饰整个类，描述Controller的作用
tags="说明该类的作用，可以在UI界面上看到的注解"

@ApiOperation：用在请求的接口方法上，描述方法的作用
value="说明方法的用途、作用"
notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数信息
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

@ApiModel：用在实体类中，描述实体类的信息等
@ApiModelProperty：描述实体类的属性
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息

配置分组

public class Swagger {
    @Bean
    public Docket customDocket1(){

        return newDocket(DocumentationType.SWAGGER_2)
        .groupName("systemManager").apiInfo(apiInfo())
        .select()
        .paths(PathSelectors.ant("/sys/**"));
        }

    @Bean
    public Docket customDocket2(){
        return newDocket(DocumentationType.SWAGGER_2)
        .groupName("userManager").apiInfo(apiInfo())
        .select()
        .paths(PathSelectors.ant("/user/**"));
        }
}

二、SpringCloud的zuul网关使用swagger2

项目结构

image.png

zuul配置

在zuul网关module中，引入Swagger的依赖，然后创建Swagger的配置文件SwaggerConfig：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Autowired
    private DiscoveryClientRouteLocator discoveryClientRouteLocator;

    @Primary
    @Bean
    public SwaggerResourcesProvider swaggerResourcesProvider() {
        return () -> {
            List<SwaggerResource> resources = new ArrayList<>();
            for (Route route : discoveryClientRouteLocator.getRoutes()) {
                resources.add(createResource(route.getLocation(),route.getId(), "2.0"));
            }
            return resources;
        };
    }

    private SwaggerResource createResource(String name, String location, String version) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation("/v2/api-docs");
        swaggerResource.setSwaggerVersion(version);
        return swaggerResource;
    }
}

就是在zuul中定义了一个路由规则，来获取2个服务的地址。

服务配置

创建了serviceOne和serviceTwo两个服务module，引入Swagger的依赖，然后创建Swagger的配置文件Swagger2：

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.com.routon"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(
                        new ApiInfoBuilder()
                                .version("1.0")
                                .title("Original Service API")
                                .description("Original Service API v1.0")
                                .build()
                );
    }
}

因为没有在项目中添加任何接口，所以其显示的是SpringBoot的默认Controller的API。

三、Spring4All封装Swagger2的使用

配置

  1. POM文件引入依赖：
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.1.RELEASE</version>
</dependency>
  1. 在启动类中使用注解开启swagger：
@EnableSwagger2Doc
@SpringBootApplication
public class SwaggerexampleApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerexampleApplication.class, args);
    }

}
  1. 在application.properties文件配置相关内容：
//标题
swagger.title=大数据展示平台项目
//描述
swagger.description=Data Display Platform
//版本
swagger.version=1.0.RELEASE
//维护人
swagger.contact.name=Dcl_Snow
//维护人URL
swagger.contact.url=https://www.cnblogs.com/dcl-snow/
//维护人邮箱
swagger.contact.email=Dcl_Snow@163.com
//swagger扫描的基础包，默认：全扫描
swagger.base-package=com.example.swaggerexample
//需要处理的基础URL规则，默认：/**
swagger.base-path=/**
  1. 在Controller接口类中进行注释，@Api、@ApiOperation是API的说明内容，@ApiImplicitParam、@ApiModel、@ApiModelProperty是参数的说明内容：
@Api(tags = "用户管理接口")
@RestController
@RequestMapping("/users")
public class UserController {
    static Map<Long,User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    @ApiOperation(value="获取用户列表", notes="")
    @RequestMapping(value = "/",method = RequestMethod.GET)
    public List<User> getUserList(){
        List<User> list = new ArrayList<>(users.values());
        return list;
    }

    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = false, dataType = "User")
    @RequestMapping(value = "",method = RequestMethod.POST)
    public String postUser(@ModelAttribute User user){
        users.put(user.getId(),user);
        return "success";
    }

    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value = "/{id}",method = RequestMethod.GET)
    public User getUser(@PathVariable Long id){
        return users.get(id);
    }

    @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = false, dataType = "User")
    })
    @RequestMapping(value = "/{id}",method = RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @ModelAttribute User user){
        User user1 = users.get(id);
        user1.setName(user.getName());
        user1.setAge(user.getAge());
        users.put(id,user1);
        return "success";
    }

    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
    public String deleteUser(@PathVariable Long id){
        users.remove(id);
        return "success";
    }
}

相关文章

网友评论

      本文标题：Swagger2的配置使用

      本文链接：https://www.haomeiwen.com/subject/gzocgctx.html

      延伸阅读

      深度阅读

      • 您也可以注册成为美文阅读网的作者，发表您的原创作品、分享您的心情！

      栏目导航

      热点阅读

      关于我们|服务条款|联系我们|Swagger2的配置使用|投稿指南|网站地图|RSS订阅|排版工具|手机版

      提供经典美文摘抄,优美散文欣赏,现代诗歌精选,短篇小说,心情随笔,表白情书范文,故事会在线阅读欣赏

      Copyright © 2014-2023 Haomeiwen.com All Rights Reserved. 好美文阅读网 版权所有

      备案信息：桂公网安备 45052102000051号 · 桂ICP备13007215号-3

      本站所收录作品、热点评论等信息部分来源互联网，目的只是为了系统归纳学习和传递资讯

      所有作品版权归原创作者所有，与本站立场无关，如不慎侵犯了你的权益，请联系我们告知，我们将做删除处理！