springfox-swagger2 springfox-swagger-ui
阿新 • • 發佈:2018-12-20
用註解的方式寫restful風格的Api文件
依賴配置
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
配置類
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.demo.controller")) //必須存在 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring 中使用Swagger2構建RESTful APIs") //標題 .description("swagger2") 描述 .contact(new Contact("姓名", "網址", "郵箱")) .version("1.1") //版本 .build(); } }
使用
@Api(value = "/test", description="使用者相關操作") @RestController @RequestMapping("/test") public class TestController { private static final Logger log = LoggerFactory.getLogger(TestController.class); @Autowired private UserDao userDao; @RequestMapping(value = "/getUserAll", method = RequestMethod.GET) @ApiOperation(value = "使用者查詢服務", notes = "查詢所有使用者") public List<User> getUserAll(){ return userDao.getAllUser(); } @RequestMapping(value = "/getUserByUsername", method = RequestMethod.GET) @ApiOperation(value = "使用者查詢服務", notes = "查詢所有使用者") public User getUserByUsername(@RequestParam @ApiParam(name="username",value="使用者名稱",required=true)String username){ return userDao.getUserByUsername(username); } @RequestMapping(value = "/showHello" ) @ApiIgnore public ModelAndView showHello() { User user = userDao.getUserByUsername("test"); return new ModelAndView("hello"); } }
@ApiIgnore()用於類,方法,方法引數 ,表示這個方法或者類被忽略
@ApiIgnore
@Api:用在請求的類上,說明該類的作用
@Api(value = "/test", description="使用者相關操作")
@ApiOperation:用在請求的方法上,說明方法的作用
@ApiOperation(value = "使用者查詢服務", notes = "查詢所有使用者")
@ApiImplicitParams:用在請求的方法上,包含一組引數說明
@ApiParam(name="username",value="使用者名稱",required=true)
@ApiImplicitParams:用在請求的方法上,包含一組引數說明
@ApiImplicitParam:用在 @ApiImplicitParams 註解中,指定一個請求引數的配置資訊
name:引數名
value:引數的漢字說明、解釋
required:引數是否必須傳
paramType:引數放在哪個地方
· header --> 請求引數的獲取:@RequestHeader
· query --> 請求引數的獲取:@RequestParam
· path(用於restful介面)--> 請求引數的獲取:@PathVariable
· body(不常用)
· form(不常用)
dataType:引數型別,預設String,其它值dataType="Integer"
defaultValue:引數的預設值
@ApiResponses:用於請求的方法上,表示一組響應
@ApiResponses:用於請求的方法上,表示一組響應
@ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應資訊
code:數字,例如400
message:資訊,例如"請求引數沒填好"
response:丟擲異常的類
@ApiModel:用於響應類上,表示一個返回響應資料的資訊
@ApiModel:用於響應類上,表示一個返回響應資料的資訊
(用在post資料時,使用@RequestBody接收引數,請求引數無法使用@ApiImplicitParam註解進行描述)
@ApiModelProperty:用在屬性上,描述響應類的屬性