Swagger2

上次給你們推薦Swagger2這個神器，自動生成接口文檔。不須要本身再專門寫文檔，對於程序員來講能提升工做效率。git

可是上篇並無講怎麼使用Wagger2這個軟件，今天就帶你們實現下。程序員

環境

使用的語言是Java,其餘語言也有類型的實現。官網連接:swagger2github

框架是SpringBoot,構建工具是gradle.spring

實現

構建組件

在微服務開發中，咱們會建立多個後端程序，在每一個程序上都將swagger2的配置寫一遍，顯得很臃腫，咱們此次在開發的時候將swagger2打形成一個組件的方式，後期直接引用。後端

新創建Gradle項目

// 增長依賴
dependencies {
    compile("io.springfox:springfox-swagger2:2.9.1")
    compile("io.springfox:springfox-swagger-ui:2.9.1")
    compile("org.springframework.boot:spring-boot-autoconfigure:1.5.10.RELEASE")
    compileOnly("org.springframework.data:spring-data-commons:1.12.6.RELEASE")
}
複製代碼

建立依賴的類

// 注意有些參數咱們是經過配置文件配置過來的
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Resource
    SwaggerProperties swaggerProperties;

    /** * 注入docket * @return: Docket * @author: fruiqi * @date: 19-2-18 下午6:20 */ 
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(createApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePacakge()))
                .paths(PathSelectors.any())
                .build();
    }

    /** * 建立api * @return: springfox.documentation.service.ApiInfo * @author: fruiqi * @date: 19-2-18 下午6:20 */ 
    private ApiInfo createApiInfo(){
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .version(swaggerProperties.getVersion())
                .build();
    }


}

複製代碼

讀取配置文件的類api

@Configuration
public class SwaggerProperties {

    /** * 標題 默認 */
    @Value("${swagger.title}")
    private String title = "標題";

    /** * 描述 */
    @Value("${swagger.description}")
    private String description = "描述";

    /** * 版本號 */
    @Value("${swagger.version}")
    private String version = "1.0.0";

    /** * 包路徑信息 */
    @Value("${swagger.basepackage}")
    private String basePacakge = "com.infervision";

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public String getVersion() {
        return version;
    }

    public void setVersion(String version) {
        this.version = version;
    }

    public String getBasePacakge() {
        return basePacakge;
    }

    public void setBasePacakge(String basePacakge) {
        this.basePacakge = basePacakge;
    }
}

複製代碼

咱們的文件屬性放到配置文件中，做爲組件內容引入到別的項目中，配置文件類中使用的屬性從其餘項目配置文件獲取。微信

其餘項目引入上面的wagger組件，組件的項目名稱
compile project(':swagger-manage') //配置文件以下 swagger: title: test description: 開發devapi version: 1.0.0 basepackage: com.infervision 複製代碼

咱們在其餘項目能夠隨意引入該組件，但更好的引入方式能夠將其打成mavenjar包，放到maven倉庫中，之後可使用maven的方式調用本身生成的swagger組件。app

使用

建立Controller類，使用不一樣的註解標識咱們建立的接口。框架

@RestController
@RequestMapping("people")
@Api(value = "people", description = "用戶控制端")
public class PeopleController {

    /** * 日誌 */
    private static final Logger logger = LoggerFactory.getLogger(PeopleController.class);

    @Autowired
    PeopleService peopleService;


    /** * 根據用戶實體內容 分類查詢用戶 * 1. 在這裏 vo層將查詢條件封裝成爲一個實體或者 * 參數較少能夠直接使用RESTful的方式將其傳參 * @param people 用戶實體 * @return: com.infervision.model.People * @author: fruiqi * @date: 19-2-20 上午10:45 */
    @GetMapping
    @ApiOperation(value = "獲取用戶列表信息", notes = "條件能夠選擇 用戶名,公司等內容")
    public List<PeopleVo> getPeoples(PeopleVo people) throws CommonException {
        List<PeopleVo> peoples = peopleService.getPeoples(people);
        return peoples;
    }


    /** * 增長用戶信息 * * @param peopleVo 增長的用戶信息 * @return: com.infervision.model.PeopleVo * @author: fruiqi * @date: 19-2-20 下午3:31 */
    @PostMapping
    @ApiOperation(value = "增長用戶")
    public PeopleVo addPeople(@RequestBody PeopleVo peopleVo) {
        PeopleVo result = peopleService.addPeople(peopleVo);
        return result;
    }

    /** * 修改對象 * @param id 用戶id * @param peopleVo 修改的對象 * @return: com.infervision.model.PeopleVo * @author: fruiqi * @date: 19-2-20 下午4:06 */
    @PutMapping("{id}")
    @ApiOperation(value="更新用戶")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name = "id",value = "用戶id",required = true)
    })
    public PeopleVo updatePeople(@PathVariable Integer id, @RequestBody PeopleVo peopleVo) {
        PeopleVo result = peopleService.updatePeople(id, peopleVo);
        return result;
    }


    @DeleteMapping("{id}")
    @ApiOperation(value="刪除用戶")
    @ApiImplicitParam(dataType = "string",name = "id",value = "用戶id",required = true)
    public void deletePeople(@PathVariable Integer id){

        if (id != null){
            peopleService.deletePeople(id);
            logger.info("[INFO] 刪除用戶id ");
        }


    }


}

複製代碼