1.pom.xml加入Swagger依賴包

<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <swagger.version>2.2.2</swagger.version>
    </properties>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

2.編寫config配置類

@Configuration   //表明該類是配置類，并創(chuàng)建bean由spring管理
@EnableSwagger2   //開啟Swagger2
public class SwaggerConfig{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //采用包含注解的方式來確定要顯示的接口
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //采用包掃描的方式來確定要顯示的接口
                //.apis(RequestHandlerSelectors.basePackage("com.xx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger標題")
                .description("Swagger描述")
                .termsOfServiceUrl("www.baidu.com")
                .contact("actor")
                .version("1.0")
                .build();
    }

}

3.添加swagger注解

由于swagger是侵入式的，但好在只需要添加相關(guān)注解，無需改動其他代碼，所以即使是舊工程新引入swagger的改動也是可以接受的

@RestController
@Api
public class GirlController {
    private final  static Logger logger = LoggerFactory.getLogger(GirlController.class);
    @Autowired
    private GirlRepository girlRepository;
    @Autowired
    private GirlService girlService;

    //查詢一個女生
    @GetMapping(value = "/girls/{id}")
    @ApiOperation(value = "測試查詢", notes = "測試根據(jù)id查詢girl", tags = {""}, response = Girl.class)
    @ApiImplicitParams({
            @ApiImplicitParam(value = "girl的id", name = "id", required = true, dataType = "int", paramType = "path"),
    })
    public Girl girlFindOne(@PathVariable("id") Integer id){
        return girlRepository.findOne(id);
    }

    //查詢一個女生
    @PostMapping(value = "/girls/detail")
    @ApiOperation(value = "測試查詢", notes = "測試根據(jù)id查詢girl", tags = {""}, response = Girl.class)
    @ApiImplicitParams({
            @ApiImplicitParam(value = "girl的id", name = "map", required = true, dataType = "map", paramType = "body"),
    })
    public Girl girlFindOnepost(@RequestBody Map<String,Object> map){
        Integer id = (Integer) map.get("id");
        System.out.println(id);
        return girlRepository.findOne(id);
    }

    //更新一個女生
    @PutMapping (value = "/girls/{id}")
    public Girl girlUpdateOne(@PathVariable("id") Integer id,
                              @RequestParam("cupSize") String cupSize,
                              @RequestParam("age") Integer age){
        Girl girl = new Girl();
        girl.setCupSize(cupSize);
        girl.setAge(age);
        girl.setId(id);
        return girlRepository.save(girl);
    }

    //刪除一個女生
    @DeleteMapping(value = "/girls/{id}")
    public void deleteGirl(@PathVariable("id") Integer id){
         girlRepository.delete(id);
    }
    //根據(jù)年齡查詢
    @GetMapping(value = "/girls/age/{age}")
    public List<Girl> girlFindByAge(@PathVariable("age") Integer age){
        return girlRepository.findByAge(age);
    }
    //測試swagger
    @RequestMapping(value = "/test/sw/{num}", method = RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value = "測試Swagger", notes = "測試SwaggerNotes", tags = {""}, response = String.class)
    @ApiImplicitParams({
            @ApiImplicitParam(value = "測試字符串", name = "str", required = true, dataType = "String", paramType = "query"),
            @ApiImplicitParam(value = "測試數(shù)字", name = "num", required = true, dataType = "int", paramType = "path"),
    })
    public String swaggerTest(@RequestParam String str,@PathVariable Integer num){
        return str + num.toString();
    }
}

4.啟動工程，訪問：(http://localhost:8080/swagger-ui.html) ，就看到swagger-ui:

swagger.png

然后就可以做一些接口測試了。

Swagger使用的注解及其說明：
@Api：用在類上，說明該類的作用。

@ApiOperation：注解來給API增加方法說明。

@ApiImplicitParams : 用在方法上包含一組參數(shù)說明。

@ApiImplicitParam：用來注解來給方法入?yún)⒃黾诱f明。

@ApiResponses：用于表示一組響應(yīng)

@ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應(yīng)信息

l   **code**：數(shù)字，例如400

l   **message**：信息，例如"請求參數(shù)沒填好"

l   **response**：拋出異常的類   

@ApiModel：描述一個Model的信息（一般用在請求參數(shù)無法使用@ApiImplicitParam注解進行描述的時候）

l   **@ApiModelProperty**：描述一個model的屬性

常用注解可以參考：Swagger 常用注解使用詳解