MyException - 我的异常网
当前位置:我的异常网» 行业应用 » 使用swagger治理接口

使用swagger治理接口

www.MyException.Cn  网友分享于:2013-12-09  浏览:0次
使用swagger管理接口

简介:Swagger是一种Rest API的 简单但强大的表示方式,标准的,语言无关,这种 表示方式不但人可读,而且机器可读。 可以作为Rest API的交互式文档,也可以作为Rest API的形式化的接口描述,生成客户端和服务端的代码。

 

下面结合比较常见的场景,大概说下在Springboot下如何使用swagger来管理接口,以便前后端开发人员能够很好的做接口的对接,同时也利于接口的后续维护开发。

 

1. maven里引入swagger所需jar包:

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
    </dependencies>

 

2.指定swagger的一些静态资源文件配置,一般用一个类来管理维护:

@Configuration
@EnableSwagger2
public class SwaggerConfiguration extends WebMvcConfigurerAdapter {

    @Value("${swagger2.basePackage:com.xxx}")
    private String swagger2BasePackage;
    @Value("${swagger2.title:系统API文档}")
    private String swagger2Title;
    @Value("${swagger2.api.version:1.0}")
    private String apiVersion;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars*").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select().apis(RequestHandlerSelectors.basePackage(swagger2BasePackage))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(swagger2Title).version(apiVersion).build();
    }
}

 

3. 如何使用?

这一步我会用比较常见的业务场景去描述接口:

首先Controller层(类)上需要这样注解:

@Api(value = "SWAGGER接口")
@RestController
@RequestMapping(value = "/api/swagger/user")
public class SwaggerController{
  //....
}

 

1)请求参数对应一组String字符串或者一个VO,返回结果是单个对象

此时方法一定要有返回而不能是void

eg:根据输入条件查询某条记录

@ApiOperation(value="获取用户详细信息", notes="根据参数来获取用户详细信息")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户ID", dataType = "Long", paramType = "query"),
        @ApiImplicitParam(name = "name", value = "用户名字", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "age", value = "用户年龄", dataType = "Long", paramType = "query")
    })
    @RequestMapping(value="", method=RequestMethod.GET)
    @PostMapping("/find1")
    public  User find (@ModelAttribute User user) {//@ModelAttribute User user 等效于Long id, String name; Long age;
        return new User();
    }

 其中User类如下:

//@ApiModel(value="User", description="用户对象")
public class User {
  @ApiModelProperty(value = "用户ID", required = true)
    private Long id;
  @ApiModelProperty(hidden = true)
    private String name;
  @ApiModelProperty(value = "用户年龄")
    private Long age;
  public void setId(Long id) {
    this.id = id;
  }
  public void setName(String name) {
    this.name = name;
  }
  public void setAge(Long age) {
    this.age = age;
  }
  public Long getId() {
    return id;
  }
  public String getName() {
    return name;
  }
  public Long getAge() {
    return age;
  }
    
}

 User类是对应查询条件或查询结果组成的实体~,每个属性需要用@ApiModelProperty去描述每个字段的含义;User类上的@ApiModel注解可以选择性给出。

 

访问swagger接口描述页面只需启动项目(这里是springboot),然后输入http://localhost:8080/swagger-ui.html#!即可访问,我们点击对应的Controller和接口,可以看到:



 

Paramters就是描述输入参数的区域,而Response则是输出的描述,Response可以切换到Model,可以看到输出的字段的具体含义:



 

2)请求参数是复合的,这时候必须对应一个实体类,如:

//@ApiModel(value="Params", description="传入参数")
public class Params {
  @ApiModelProperty(name="param1", value = "参数1", required = true)
  private String param1;
  
  @ApiModelProperty(name="input", value = "输入", required = true)
  private List<Input> input;
  
  public String getParam1() {
    return param1;
  }

  public void setParam1(String param1) {
    this.param1 = param1;
  }

  public List<Input> getInput() {
    return input;
  }

  public void setInput(List<Input> input) {
    this.input = input;
  }

}

 

返回是一个集合类型:

@ApiOperation(value="获取用户信息集合", notes="根据输入类型来获取用户信息集合")
    @PostMapping("/find2")
    @ApiResponse(response = User.class, responseContainer="List", code = 200, message = "请求成功")
    public List<User> find2(@ApiParam(value="传入参数类型", required=true) @RequestBody Params params) {
      
      return new ArrayList<User>();
    }

 

ui上点击对应方法,可以看到:



 

 

可以看到,现在无论是对于接口里再复杂的输入和输出,都能比较清楚地看到每个属性(字段)的含义,以及可以在swagger的ui上直接用Try it out 按钮来测试接口的可用性。

 

swagger可以很好地帮助我们管理项目接口~,以及不同业务侧之间的接口对接工作。

文章评论

“肮脏的”IT工作排行榜
“肮脏的”IT工作排行榜
程序员周末都喜欢做什么?
程序员周末都喜欢做什么?
科技史上最臭名昭著的13大罪犯
科技史上最臭名昭著的13大罪犯
Java 与 .NET 的平台发展之争
Java 与 .NET 的平台发展之争
为啥Android手机总会越用越慢?
为啥Android手机总会越用越慢?
总结2014中国互联网十大段子
总结2014中国互联网十大段子
团队中“技术大拿”并非越多越好
团队中“技术大拿”并非越多越好
写给自己也写给你 自己到底该何去何从
写给自己也写给你 自己到底该何去何从
我的丈夫是个程序员
我的丈夫是个程序员
程序员的鄙视链
程序员的鄙视链
旅行,写作,编程
旅行,写作,编程
做程序猿的老婆应该注意的一些事情
做程序猿的老婆应该注意的一些事情
为什么程序员都是夜猫子
为什么程序员都是夜猫子
老美怎么看待阿里赴美上市
老美怎么看待阿里赴美上市
我跳槽是因为他们的显示器更大
我跳槽是因为他们的显示器更大
10个调试和排错的小建议
10个调试和排错的小建议
“懒”出效率是程序员的美德
“懒”出效率是程序员的美德
程序员最害怕的5件事 你中招了吗?
程序员最害怕的5件事 你中招了吗?
程序员眼里IE浏览器是什么样的
程序员眼里IE浏览器是什么样的
初级 vs 高级开发者 哪个性价比更高?
初级 vs 高级开发者 哪个性价比更高?
一个程序员的时间管理
一个程序员的时间管理
代码女神横空出世
代码女神横空出世
Java程序员必看电影
Java程序员必看电影
要嫁就嫁程序猿—钱多话少死的早
要嫁就嫁程序猿—钱多话少死的早
2013年美国开发者薪资调查报告
2013年美国开发者薪资调查报告
 程序员的样子
程序员的样子
程序猿的崛起——Growth Hacker
程序猿的崛起——Growth Hacker
十大编程算法助程序员走上高手之路
十大编程算法助程序员走上高手之路
Web开发人员为什么越来越懒了?
Web开发人员为什么越来越懒了?
Web开发者需具备的8个好习惯
Web开发者需具备的8个好习惯
聊聊HTTPS和SSL/TLS协议
聊聊HTTPS和SSL/TLS协议
2013年中国软件开发者薪资调查报告
2013年中国软件开发者薪资调查报告
10个帮程序员减压放松的网站
10个帮程序员减压放松的网站
程序员和编码员之间的区别
程序员和编码员之间的区别
当下全球最炙手可热的八位少年创业者
当下全球最炙手可热的八位少年创业者
程序员的一天:一寸光阴一寸金
程序员的一天:一寸光阴一寸金
编程语言是女人
编程语言是女人
每天工作4小时的程序员
每天工作4小时的程序员
Google伦敦新总部 犹如星级庄园
Google伦敦新总部 犹如星级庄园
老程序员的下场
老程序员的下场
漫画:程序员的工作
漫画:程序员的工作
程序员应该关注的一些事儿
程序员应该关注的一些事儿
5款最佳正则表达式编辑调试器
5款最佳正则表达式编辑调试器
那些性感的让人尖叫的程序员
那些性感的让人尖叫的程序员
程序员都该阅读的书
程序员都该阅读的书
如何区分一个程序员是“老手“还是“新手“?
如何区分一个程序员是“老手“还是“新手“?
那些争议最大的编程观点
那些争议最大的编程观点
中美印日四国程序员比较
中美印日四国程序员比较
什么才是优秀的用户界面设计
什么才是优秀的用户界面设计
软件开发程序错误异常ExceptionCopyright © 2009-2015 MyException 版权所有