swagger

主要是为后端服务的接口文档，懒人必备，swagger就是一款让你更好的书写API文档的框架。
其他的框架有阿里爸爸推出 Rap ，感兴趣的可以自己了解一下。
本文主要基于springboot，要先了解下springboot；

开始

Maven

本项目基于maven
springboot pom 中添加

  <!-- swagger --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.5.0</version></dependency><!-- swagger-ui --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.5.0</version></dependency><dependency><groupId>io.github.swagger2markup</groupId><artifactId>swagger2markup-spring-restdocs-ext</artifactId><version>2.5.0</version><scope>test</scope></dependency>

启动

package com.example.demo;import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;/*** @author Dwxqnswxl*/
@EnableAutoConfiguration
@SpringBootApplication(scanBasePackages = "com.example")
public class DemoApplication {public static void main(String[] args) {SpringApplication.run(DemoApplication.class, args);}
}

配置

import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** Description** @Author : huangjinxing* @Email : hmm7023@gmail.com* @Date : 2018/10/24 11:10* @Version :*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket swaggerSpringMvcPlugin() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();}@Beanpublic ApiInfo apiInfo() {return new ApiInfoBuilder().title("接口列表 v1.1.0").description("接口测试").termsOfServiceUrl("http://localhost:8080/").contact(new Contact("HUANGJINXING","www.dwxqnswxl.cn","hmm7023@gmail.com")).version("1.1.0").build();}}

Controller

package com.example.controller;import com.example.bean.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.context.request.async.DeferredResult;import java.util.HashMap;
import java.util.Map;/*** Description** @Author : huangjinxing* @Email : hmm7023@gmail.com* @Date : 2018/10/24 11:12* @Version :*/
@Api()
@RestController
@RequestMapping("/demoController")
public class DemoController {private static final Logger log = LoggerFactory.getLogger(DemoController.class);public static final String RET_CODE = "retCode";public static final String RET_MSG = "retMsgo";@ApiOperation(value = "新增用户", notes = "新增注册")@PostMapping(value = "/createUser", consumes = MediaType.APPLICATION_JSON_VALUE)public DeferredResult createUser(@RequestBody User user) {log.info("createUser:::" , user.toString());DeferredResult deferredResult = new DeferredResult();Map map = new HashMap();map.put(RET_CODE, HttpStatus.OK.value());map.put(RET_MSG, "新增成功.");deferredResult.setResult(map);return deferredResult;}@ApiOperation(value = "修改用户", notes = "修改用户")@PostMapping(value = "/updateUser", consumes = MediaType.APPLICATION_JSON_VALUE)public DeferredResult updateUser(@RequestBody User user) {log.info("updateUser:::" , user.toString());DeferredResult deferredResult = new DeferredResult();Map map = new HashMap();map.put(RET_CODE, HttpStatus.OK.value());map.put(RET_MSG, "修改成功.");deferredResult.setResult(map);return deferredResult;}@ApiOperation(value = "删除用户", notes = "删除用户")@ApiImplicitParams({@ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")})@DeleteMapping(value = "/deleteUser")public DeferredResult deleteUser(@RequestParam("userId") String userId) {log.info("deleteUser:::" , userId);DeferredResult deferredResult = new DeferredResult();Map map = new HashMap();map.put(RET_CODE, HttpStatus.OK.value());map.put(RET_MSG, "删除成功.");deferredResult.setResult(map);return deferredResult;}@ApiOperation(value = "查询用户", notes = "查询用户")@ApiImplicitParams({@ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")})@GetMapping(value = "/queryUser")public DeferredResult queryUser(@RequestParam("userId") String userId) {log.info("queryUser:::" , userId);DeferredResult deferredResult = new DeferredResult();Map map = new HashMap();map.put(RET_CODE, HttpStatus.OK.value());map.put(RET_MSG, "查询成功.");map.put("username", "张三.");map.put("password", "123456");deferredResult.setResult(map);return deferredResult;}
}

User类

package com.example.bean;/*** Description** @Author : huangjinxing* @Email : hmm7023@gmail.com* @Date : 2018/10/24 11:16* @Version :*/
public class User {private String username;private String password;public String getUsername() {return username;}public void setUsername(String username) {this.username = username;}public String getPassword() {return password;}public void setPassword(String password) {this.password = password;}@Overridepublic String toString() {return "User{" +"username='" + username + '\'' +", password='" + password + '\'' +'}';}
}

启动

登陆 http://localhost:8080/swagger-ui.html#/
就可以看到有UI的 接口 
swagger的功能不止如此。

效果